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This book, intended mainly for the programmer coding in assembler language, describes how to 
use the services of the supervisor, the macro instructions used to request these services, and the 
linkage conventions used by the control program to provide these services. 

The system programmer interested in additional information on the supervisor should see 
MVS I Extended Architecture System Programming Library: System Macros and Facilities 
Volume 1, GC28-1150 and Volume 2, GC28-1151. 

This book is divided into two parts. Part I, "Supervisor Services," provides explanations and 
aids for using the facilities available through the supervisor. Part II, "Macro Instructions," 
provides coding information. 

Part I is divided into eight topics. Specific topics include: 

• Linkage Conventions 

• Subtask Creation and Control 

• Program Management 

• Resource Control 

• Program Interruption, Termination, and Dumping Services 

• Virtual Storage Management 

• Real Storage Management 

• Data in Virtual Facility 

• Miscellaneous Services 

Part II contains the descriptions and definitions of the supervisor macro instructions available 
in the assembler language. It provides applications programmers coding the assembler language 
with the information necessary to code the macro instructions. The standard, list, and execute 
forms of the macro instructions are grouped, where applicable, for ease of reference. 

Use of this book requires a basic knowledge of the operating system and of assembler language. 
Books that contain basic information are: 

Assembler H Version 2 Application Programming: Language Reference, GC26-4037 

MVS I Extended Architecture Checkpoint! Restart User's Guide, GC26-4012 

MVS/Extended Architecture Data Administration Macro Instruction Reference, GC26-4014 

MVS I Extended Architecture Data Administration Guide, GC26-4013 

MVS/Extended Architecture Linkage Editor and Loader User's Guide, GC26-4011 

MVS/Extended Architecture Message Library: Routing and Descriptor Codes, GC28-1194 
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MV SI Extended Architecture Operations: JES3 Commands, SC23-0063 

MVSI Extended Architecture Operations: System Commands, GC28-1206 

OS/VS2 MVS Planning: Global Resource Serialization, GC28-1062 

MVSI Extended Architecture System Programming Library: Initialization and Tuning, 
GC28-1149 

MVSI Extended Architecture System Programming Library: Service Aids, GC28-1159 

MVSfExtended Architecture System Programming Library: System Macros and Facilities 
Volume 1, GC28- 11 50 

MVS) Extended Architecture System Programming Library: System Macros and Facilities 
Volume 2, GC28-1 151 

MVSI Extended Architecture System Programming Library: System Modifications, 
GC28-1152 

Resource Access Control Facility (RACE): General Information Manual, GC28-0722 

System Programming Library: Resource Access Control Facility (RACF), SC28-1343 

370-Extended Architecture: Principles of Operation, GA22-7085 

MVS/Extended Architecture: Integrated Catalog Administration: Access Method Services 



Reference, GC26-4135 ^ 

Notes: 

1. All references to RACF in this publication indicate the program product Resource Access 
Control Facility Version 1 Release 7 (5740-XXH). 

2. All references to Assembler H in this publication indicate the program product Assembler H 
Version 2 (5668-962). 
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The supervisor provides the resources that your programs need while assuring that as many of 
these resources as possible are being used at a given time. Well designed programs use system 
resources efficiently. Knowing the conventions and characteristics of the supervisor will help 
you design more efficient programs. 

The services you can request from the supervisor are discussed in chapters dealing with the 
following topics: 

Subtask Creation and Control: Occasionally, you can have your program executed faster and 
more efficiently by dividing parts of it into subtasks that compete with each other and with 
other tasks for execution time. 

Program Management: You can use the supervisor to aid communication between segments of 
a program. Residency and addressing mode of programs and linkage considerations for 
MVS/XA are discussed in this chapter. Save areas, addressability, and passage of control from 
one segment of a program to another are also discussed. 

Resource Control: Portions of some tasks are dependent on the completion of events in other 
tasks, thus requiring planned task synchronization. Planning is also required when more than 
one program uses a serially reusable resource. 

Program Interruption, Termination, and Dumping Services: The supervisor provides facilities for 
writing exit routines to handle specific types of interruptions. It is not likely, however, that you 
will be able to write routines to handle all types of abnormal conditions. The supervisor 
therefore provides for termination of your program when you request it by issuing an ABEND 
macro instruction, or when the control program detects a condition that will degrade the system 
or destroy data. 

Virtual Storage Management: While virtual storage allows you to write large programs without 
the need for complex overlay structures, virtual storage must be obtained for your job step. 
Virtual storage is allocated by both explicit and implicit requests. 

Real Storage Management: The supervisor administers the use of real storage and directs the 
movement of virtual pages between auxiliary storage and real storage in page size blocks. The 
services provided allow you to release virtual storage contents, load virtual storage areas into 
real storage, and page out virtual storage areas from real storage. 

In addition to the services outlined above, the supervisor provides the facilities for timing 
events, and operator communication with both the system and application programs. 
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You should design all programs, regardless of their function or relative position in the task, 
using certain conventions and with certain characteristics of the control program in mind. This 
chapter describes these conventions and characteristics and tells how they affect the execution 
of your program. See the "Program Management" chapter for information about linkage 
considerations for MVS/XA. 

During the execution of a program the services of another program may be required. The 
program that requests the services of another program is known as a calling program, and the 
program that was requested is known as the called program. For example, when the control 
program passes control to program A, program A becomes a called program. If program A in 
turn passes control to program B, program A becomes a calling program, and program B 
becomes a called program. From the point of view of the control program, however, program 
A remains a called program until control is returned by program A. For more information on 
this subject, see the discussion under the heading "Task and Subtask Communications" in 
"Subtask Creation and Control." 

The following conventions are presented assuming one calling and one called program. They 
apply, however, to all called and calling programs operating in the system. If the conventions 
presented here are always followed, execution of the called program will not be affected by the 
method used to pass control or by the identity of the calling program. 
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Registers 0, 1, 13, 14, and 15 are known as the linkage registers; they are used in fixed ways by 
the control program. It is good practice to use these registers in the same way in your program, 
since they may be modified by the control program or by your program when system macro 
instructions are used. Registers 2-12 are not changed by the control program. 

Registers and 1 are used to pass parameters to the control program or to a called program. 
The expansions of some system macro instructions result in instructions that load a value into 
register or 1 or both, or load the address of a parameter list into register 1. For other macro 
instructions, the control program uses register 1 to pass specified parameters to the program 
you call. 

Register 13 contains the address of the save area provided by the calling program. 

Register 14 contains the return address of the calling program or an address within the control 
program to which your program is to return control when it has completed execution. 

Register 1 5 contains the entry address when control is passed to your program by the control 
program. The entry address of the called routine should be in register 1 5 when you pass 
control to another program. The expansion of some macro instructions results in instructions 
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that load into register 15 the address of a parameter list to be passed to the control program. 
Register 15 is also used by the called program to return a value (a return code) to the calling 
program. 

The manner in which the control program passes the information in the PARM field of your 
EXEC statement is a good example of how the control program uses a parameter register to 
pass information. When control is passed to your program from the control program, register 1 
contains the address of a fullword on a fullword boundary in your area of virtual storage (refer 
to Figure 1). The high-order bit (bit 0) of this word is set to 1. This is a convention used by 
the control program to indicate the last word in a variable-length parameter list; you must use 
the same convention when making requests to the control program. Bits 1-31 of the fullword 
contain the address of a two-byte length field on a halfword boundary. The length field 
contains a binary count of the number of bytes in the PARM field, which immediately follows 
the length field. If the PARM field was omitted in the EXEC statement, the count is set to 
zero. To prevent possible errors, the count should always be used as a length attribute in 
acquiring the information in the PARM field. If your program is not going to use this 
information immediately, you should load the address from register 1 into one of registers 2-12 
or store the address in a fullword in your program. 
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Figure 1. Acquiring PARM Field Information 
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The first action a called program should take is to save the contents of the calling program's 
registers. The contents of any register the called program modifies and the contents of the 
linkage registers must be saved. All registers should be saved to avoid errors when the called 
program is modified. 

The registers are saved in the 18 -word save area provided by the calling program and pointed to 
by register 13. The format of this area is shown in Figure 2. As indicated by this figure, the 
contents of each register must be saved in a specific location within the save area. Registers can 
be saved either with a store-multiple (STM) instruction or with the SAVE macro instruction. 
The store-multiple instruction, STM 14,12,12(13), places the contents of all registers except 13 
in the proper words of the save area. Saving register 13 is discussed under the heading 
"Providing a Save Area." 



Word 
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1 


Used by PL/I language program 
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Address of previous save area (stored by calling program) 
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Address of next save area (stored by current program) 


4 


Register 14 (Return address) 


5 


Register 15 (Entry address) 


6 


Register 


7 


Register 1 


8 


Register 2 


9 


Register 3 


10 


Register 4 


11 


Register 5 


12 


Register 6 


13 


Register 7 


14 


Register 8 


15 


Register 9 


16 


Register 10 


17 


Register 11 
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Figure 2. Format of the Save Area 

The SAVE macro instruction generates instructions that store a designated group of registers in 
the save area. The registers to be saved are coded in the same order as in an STM instruction. 
Figure 3 illustrates uses of the SAVE macro instruction. The T parameter (in B) specifies that 
the contents of registers 14 and 15 are to be saved. 



(A) PROGNAME SAVE (14,12) 

(B) PROGNAME SAVE (5,10) ,T 



Figure 3. Use of the SAVE Macro Instruction 

The SAVE macro instruction or the equivalent instructions should be placed at the entry point 
to the program. 
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Establishing a Base Register 



In MVS/XA, addresses are resolved by adding a displacement to a base address. You must, 
therefore, establish a base register using one of the registers from 2-12 or register 15. If your 
program does not use system macro instructions and does not pass control to another program, 
you can establish a base register using the entry address in register 15. Otherwise, because both 
your program and the control program use register 15 for other purposes, you must establish a 
base using one of the registers 2-12. This should be done immediately after saving the calling 
program's registers. 

Note: Cautiously choose your base registers keeping in mind that some instructions alter 
register contents (for example, TRT alters register 2). A complete list of instructions and their 
processing is available in Principles of Operation. 
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If any control section in your program passes control to another control section, your program 
must provide its own save area. You must also provide a save area when you use certain 
system functions, such as GET or PUT. If you establish which registers are available to the 
called program or control section, a save area is not necessary. Omitting the save area is not a 
good coding practice, however, since any changes in your program might necessitate changing a 
called program. 

Whether or not your program provides a save area, you must save the address of the calling 

program's save area, which you used, because you will need it to restore the registers before you U 

return control to the program that called you. If you are not providing a save area, you can 

keep the address in register 13 or store it in a location in virtual storage. If you are creating 

your own save area, use the following procedure. 

• Store the address of the save area that you used (the address passed to you in register 13) in 
the second word of the save area you created. 

• Store the address of your save area (the address you will pass in register 13) in the third 
word of the calling program's save area. 

This procedure enables you to find the save area when you need it to restore the registers, and 
it enables a trace from save area to save area should one be necessary during a dump. 

Figure 4 and Figure 5 show two methods of obtaining a save area and of saving all the 
registers, including the addresses of the two save areas. In Figure 4 the registers are stored in 
the save area provided by the calling program by using the STM instruction. Register 12 is 
then established as the base register. The address of the caller's save area is then saved in the 
second word of the new save area, established by the DC statement. The address of the calling 
program's save area is loaded into register 2. The address of the new save area is loaded into 
register 13, and then stored in the third word of the caller's save area. 
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Figure 4. Chaining Save Areas in a Nonreenterable Program 

In Figure 5, the SAVE macro instruction is used to store registers. (An STM instruction could 
have been used.) The entry address is loaded into register 12, which is established as the base 
register. An unconditional GETMAIN macro instruction (discussed in detail under the heading 
"Virtual Storage Management") is issued requesting the control program to allocate 72 bytes of 
virtual storage from an area outside your program, and to return the address of the area in 
register 1. The addresses of the old and new save areas are stored in the assigned locations, and 
the address of the new save area is loaded into register 13. 
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Figure 5. Chaining Save Areas in a Reenterable Program 
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Summary of Conventions to be Followed When Passing and 
Receiving Control 

The following is a list of conventions to be followed when passing and receiving control. The 
actual methods of passing control are described under the heading "Program Management." 

By a calling program before passing control (return required): 

• Place the address of your save area in register 13. 

• Place the address at which you wish to regain control (the return address) in register 14. 

• Place the entry address of the program you are calling in register 15. 

• Place the address of the parameter list (if there is one) in register 1 . (Passing parameters is 
discussed under "Program Management.") 

By a calling program before passing control (no return required): 

• Restore registers 2-12 and 14. 

• Place the address of the save area provided by the program that called you in register 13. 

• Place the entry address of the program you are calling in register 15. 

• Place the addresses of parameter lists in registers 1 and 0. 
By a called program upon receiving control: 

• Save the contents of registers 0-12, 14, and 15 in the save area provided by the calling 
program. 

• Establish a base register. 

• Request the control program to allocate storage for a save area if you did not already 
allocate it by using a DC statement. 

• Store the save area addresses in the assigned locations. 
By a called program before returning control: 

• Restore registers 0-12 and 14. 

• Place the address of the save area provided by the program you are returning control to in 
register 13. 

• Place a return code in register 15 if one is required. Otherwise, restore register 15. 
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Subtask Creation and Control 



One task is created in the address space by the control program as a result of initiating 
execution of the job step (the job step task). You can create additional tasks in your program. 
If you do not, however, the job step task is the only task in the address space being executed. 
The benefits of a multiprogramming environment are still available even with only one task in 
the job step; work is still being performed for other address spaces when your task is waiting 
for an event, such as an input operation, to occur. 

The advantage in creating additional tasks within the job step is that more tasks are competing 
for control. When a wait condition occurs in one of your tasks, it is not necessarily a task from 
some other address space that gets control; it may be one of your tasks, a portion of your job. 

The general rule is that parallel execution of a job step (that is, more than one task in an 
address space) should be chosen only when a significant amount of overlap between two or 
more tasks can be achieved. The amount of time taken by the control program in establishing 
and controlling additional tasks, and your increased effort to coordinate the tasks and provide 
for communications between them must be taken into account. 



Creating the Task 
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A new task is created by issuing an ATTACH macro instruction. The task that is active when 
the ATTACH macro instruction is issued is the originating task; the newly created task is the 
subtask of the originating task. The subtask competes for control in the same manner as any 
other task in the system, on the basis of priority (both address space priority and task priority 
within the address space) and the current ability to use a processor. The address of the task 
control block for the subtask is returned in register 1. 

If the ATTACH macro instruction is executed successfully, control is returned to the user with 
a return code of X'OO' in register 15. 

The entry point in the load module to be given control when the subtask becomes active is 
specified as it is in a LINK macro instruction, that is, through the use of the EP, EPLOC, and 
DE parameters. The use of these parameters is discussed in "Program Management." 
Parameters can be passed to the subtask using the PARAM and VL parameters, also described 
under "The LINK Macro Instruction." Additional parameters deal with the priority of the 
subtask, provide for communication between tasks, specify libraries to be used for program 
linkages, and establish an error recovery environment for the new subtask. 

CAUTION 

All modules contained in the libraries for a job step should be uniquely named. If 

duplicate module names are contained in these libraries, the results are 

unpredictable. 
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Priorities 



There are really three priorities to consider: address space priorities, task priorities, and subtask 
priorities. 
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Address Space Priority 



When each job is initiated, an address space is created. All successive steps in the job execute 
in the same address space. The address space has a dispatching priority, which is normally 
determined by the control program. The control program will select, and alter, the priority in 
order to achieve the best load balance in the system - that is, in order to make the most 
efficient use of processor time and other system resources. 

It may be desirable for some jobs to execute at a different address space priority than the 
default priority assigned by the system. To assign a priority, you code 
DPRTY = (value l,value2) on the EXEC statement. The address space priority is then 
determined as follows: 

address space dispatching priority = (value 1 x 16) + value2 

Once the address space dispatching priority is set, it can be altered only by the control program. 
(Thus, there is no limit priority associated with an address space.) However, a new address 
space priority may be set for succeeding job steps by specifying different values in the DPRTY 
parameter on the EXEC statement. 

The IEAIPSxx and IEAICSxx members of SYS1.PARMLIB can override the dispatching 
priority specified by the DPRTY parameter. The control program assigns the priority obtained 
from IEAIPSxx to jobsteps that request a dispatching priority falling within specific installation 
defined limits. IEAICSxx directs jobs into specific performance groups thereby affecting their 
priority. See SPL: Initialization and Tuning for additional information. 



Task Priority 



Each task in an address space has associated with it a limit priority and a dispatching priority. 
These priorities are set by the control program when a job step is initiated. When other tasks 
are created in the address space by use of the ATTACH macro instruction, they may be given 
different limit and dispatching priorities by use of the LPMOD and DPMOD parameters, 
respectively. 

The task dispatching priorities of the tasks in an address space do not affect the order in which 
the jobs are selected for execution because the order is selected on the basis of address space 
dispatching priority. Once an address space is selected for dispatching, the highest priority task 
awaiting execution is selected. Thus, task priorities may affect processing within an address 
space. Note, however, that in a multiprocessing system, task priorities cannot guarantee the 
order in which the tasks will execute because more than one task may be executing 
simultaneously in the same address space on different processors. In a paging environment, 
page faults may alter the order in which the tasks execute. 
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Subtask Priority 

p When a subtask is created, the limit and dispatching priorities of the subtask are the same as 

the current limit and dispatching priorities of the originating task except when the subtask 
priorities are modified by the LPMOD and DPMOD parameters of the ATTACH macro 
instruction. The LPMOD parameter specifies the number to be subtracted from the current 
limit priority of the originating task. The result of the subtraction is assigned as the limit 
priority of the subtask. If the result is zero or negative, zero is assigned as the limit priority. 
The DPMOD parameter specifies the number to be added to the current dispatching priority of 
the originating task. The result of the addition is assigned as the dispatching priority of the 
subtask, unless the number is greater than the limit priority or less than zero. In that case, the 
limit priority or 0, respectively, is used as the dispatching priority. 

Assigning and Changing Priority 

Tasks with a large number of input/output operations should be assigned a higher priority than 
tasks with little input/output, because the tasks with much input/output will be in a wait 
condition for a greater amount of time. The lower priority tasks will be executed when the 
higher priority tasks are in a wait condition. As the input/output operations are completed, the 
higher priority tasks get control, so that more I/O can be started. 

The priorities of subtasks can be changed by using the CHAP macro instruction. The CHAP 
macro instruction changes the dispatching priority of the active task or one of its subtasks by 
adding a positive or negative value. The dispatching priority of an active task can be made less 
than the dispatching priority of another task. If this occurs, if the other task is dispatchable it 
would be given control after execution of the CHAP macro instruction. 

The CHAP macro instruction can also be used to increase the limit priority of any of an active 
task's subtasks. An active task cannot change its own limit priority. The dispatching priority 
of a subtask can be raised above its own limit priority, but not above the limit of the 
originating task. When the dispatching priority of a subtask is raised above its own limit 
priority, the subtask's limit priority is automatically raised to equal its new dispatching priority. 

Task and Subtask Communications 

The task management information in this section is required only for establishing 
communications among tasks in the same job step. The relationship of tasks in a job step is 
shown in Figure 6. The horizontal lines in Figure 6 separate originating tasks and subtasks; 
they have no bearing on task priority. Tasks A, Al, A2, A2a, B, Bl and Bla are all subtasks 
of the job-step task; tasks Al, A2, and A2a are subtasks of task A. Tasks A2a and Bla are the 
lowest level tasks in the job step. Although task Bl is at the same level as tasks Al and A2, it 
is not considered a subtask of task A. 

Task A is the originating task for both tasks Al and A2, and task A2 is the originating task for 
task A2a. A hierarchy of tasks exists within the job step. Therefore the job step task, task A, 
and task A2 are predecessors of task A2a, while task B has no direct relationship to task A2a. 
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Task A1 



Task A2 



Task B1 



Task A2a 



Task B1a 



Figure 6. Levels of Tasks in a Job Step 

All of the tasks in the job step compete independently for processor time; if no constraints are 
provided, the tasks are performed and are terminated asynchronously. However, since each 
task is performing a portion of the same job step, some communication and constraints between 
tasks are required, such as notification of the completion of subtasks. If termination of a 
predecessor task is attempted before all of the subtasks are complete, those subtasks and the 
predecessor task are abnormally terminated. 

Two parameters, the ECB and ETXR parameters, are provided in the ATTACH macro 
instruction to assist in communication between a subtask and the originating task. These 
parameters are used to indicate the normal or abnormal termination of a subtask to the 
originating task. If the ECB or ETXR parameter, or both, are coded in the ATTACH macro 
instruction, the task control block of the subtask is not removed from the system when the 
subtask is terminated. The originating task must remove the task control block from the 
system after termination of the subtask by issuing a DETACH macro instruction. If the ECB 
parameter is specified in the ATTACH macro instruction, the ECB must be in storage so that 
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the issuer of the attach can wait on it (using the WAIT macro instruction) and the control 
program can post it on behalf of the terminating task. The task control blocks for all subtasks 
must be removed before the originating task can terminate normally. 

The ETXR parameter specifies the address of an end-of-task exit routine in the originating task, 
which is to be given control when the subtask being created is terminated. The end-of-task 
routine is given control asynchronously after the subtask has terminated and must therefore be 
in virtual storage when it is required. After the control program terminates the subtask, the 
end-of-task routine specified is scheduled to be executed. It competes for CPU time using the 
priority of the originating task and of its address space and can be given control even though 
the originating task is in the wait condition. Although the DETACH macro instruction does 
not have to be issued in the end-of-task routine, this is a good place for it. 

The ECB parameter specifies the address of an event control block (discussed under "Task 
Synchronization"), which is posted by the control program when the subtask is terminated. 
After posting occurs, the event control block contains the completion code specified for the 
subtask. 

If neither the ECB nor the ETXR parameter is specified in the ATTACH macro instruction, the 
task control block for the subtask is removed from the system when the subtask is terminated. 
Its originating task does not have to issue a DETACH macro instruction. A reference to the 
task control block in a CHAP or a DETACH macro instruction in this case is risky as is task 
termination. Since the originating task is not notified of subtask termination, you may refer to 
a task control block that has been removed from the system, which would cause the active task 
to be abnormally terminated. 
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Program Management 



This chapter discusses facilities that will help you to design your programs. It includes 
descriptions of the residency mode and addressing mode of programs, linkage considerations for 
MVS/XA, load module structures, facilities for passing control between programs, and the use 
of the associated macro instructions. 



Residency and Addressing Mode of Programs 
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The control program ensures that each load module is loaded above or below 16 megabytes 
(Mb) virtual as appropriate and that it is invoked in the correct addressing mode (24-bit or 
31 -bit). The placement of the module above or below 16 Mb depends on the residency mode 
(RMODE) that you define for the module. Whether a module executes in 24-bit or 31 -bit 
addressing mode depends on the addressing mode (AMODE) that you define for the module. 

When a program is executing in 24-bit addressing mode, the system treats both instruction and 
data addresses as 24-bit addresses. This allows programs executing in 24-bit addressing mode 
to address 16 megabytes (16,777,216 bytes) of storage. Similarly, when a program is executing 
in 31 -bit addressing mode, the system treats both instruction and data addresses as 31 -bit 
addresses. This allows a program executing in 31 -bit addressing mode to address 2 gigabytes 
(2,147,483,648 bytes or 128 x 16 megabytes) of storage. 

You can define the residency mode and the addressing mode of a program in the source code. 
Figure 7 shows an example of the definition of the AMODE and RMODE attributes in the 
source code. This example defines the addressing mode of the load module as 31 -bit and the 
residency mode of the load module as 24-bit. Therefore, the program will receive control in 
31 -bit addressing mode and will reside below 16 Mb. 



SAMPLE CSECT 
SAMPLE AMODE 31 
SAMPLE RMODE 24 



Figure 7. Assembler Definition of AMODE/RMODE 

Version 2 of Assembler H places the AMODE and RMODE in the external symbol dictionary 
(ESD) of the output object module for use by the linkage editor. The linkage editor passes this 
information on to the control program through the directory entry for the partitioned data set 
(PDS) that contains the load module and the composite external symbol dictionary (CESD) 
record in the load module. You can also specify the AMODE/RMODE attributes of a load 
module by using linkage editor control cards. SPL: 31-bit Addressing contains additional 
information about residency and addressing mode; Linkage Editor and Loader contains 
information about the linkage editor control cards. 
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Residency Mode Definitions 



The control program uses the RMODE attribute from the PDS directory entry for the module 
to load the program above or below 16 Mb. The RMODE attribute can have one of the 
following values: 

24 specifies that the program must reside in 24-bit addressable virtual storage. 

ANY specifies that the program can reside anywhere in virtual storage because the code has no virtual storage 
residency restrictions. 

Note: The default value for RMODE is 24. 



Addressing Mode Definitions 



The AMODE attribute, located in the PDS directory entry for the module, specifies the 
addressing mode that the module expects at entry. Bit 32 of the program status word (PSW) 
indicates the addressing mode of the program that is executing. MVS/XA supports programs 
that execute in either 24-bit or 31 -bit addressing mode. The AMODE attribute can have one of 
the following values: 

24 specifies that the program is to receive control in 24-bit addressing mode. 

31 specifies that the program is to receive control in 31 -bit addressing mode. 

ANY specifies that the program is to receive control in either 24-bit or 31 -bit addressing mode. 

Note: The default value for AMODE is 24. 



Linkage Considerations for MVS/XA 



MVS/XA supports programs that execute in either 24-bit or 31 -bit addressing mode. The 
following branch instructions take addressing mode into consideration: 

Branch and link (BAL) 

Branch and link, register form (BALR) 

Branch and save (BAS) 

Branch and save, register form (BASR) 

Branch and set mode (BSM) 

Branch and save and set mode (BASSM) 

See Principles of Operation for a complete description of how these instructions function. The 
following paragraphs provide a general description of these branch instructions in MVS/XA. 

The BAL and BALR instructions are unconditional branch instructions (to the address in 
operand 2). BAL and BALR function differently depending on the addressing mode in which 
you are executing. The difference is in the linkage information passed in the link register when 
these instructions execute. In 31>bit addressing mode, the link register contains the AMODE 
indicator (bit 0) and the address of the next sequential instruction (bits 1-31); in 24-bit 
addressing mode, the link register contains the instruction length code, condition code, program 
mask, and the address of the next sequential instruction. 

BAS and BASR perform the same function that BAL and BALR perform when BAL and 
BALR execute in 31 -bit addressing mode. 
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The BSM instruction provides problem programs with a way to change the AMODE bit in the 
PSW. BSM is an unconditional branch instruction (to the address in operand 2) that saves the 
current AMODE in the high-order bit of the link register (operand 1), and sets the AMODE 
indicator in the PSW to agree with the AMODE of the address to which you are transferring 
control (that is, the high order bit of operand 2). 

The BASSM instruction functions in a manner similar to the BSM instruction. In addition to 
saving the current AMODE in the link register, setting the PSW AMODE bit, and transferring 
control, BASSM also saves the address of the next sequential instruction in the link register 
thereby providing a return address. 

BASSM and BSM are used for entry and return linkage in a manner similar to BALR and BR. 
The major difference from BALR and BR is that BASSM and BSM can save and change 
addressing mode. 

Passing Control Between Programs with the Same AMODE 

If you are passing control between programs that execute in the same addressing mode, there 
are several combinations of instructions that you can use. Some of these combinations are: 

Transfer Return 

BAL/BALR BR 

BAS/BASR BR 

Passing Control Between Programs with Different AMODEs 

If you are passing control between programs executing in different addressing modes, the 
AMODE indicator in the PSW must be changed. The BASSM and BSM instructions perform 
this function for you. You can transfer to a program in another AMODE using a BASSM 
instruction and then return by means of a BSM instruction. This sequence of instructions 
ensures that both programs execute in the correct AMODE. 

Figure 8 shows an example of passing control between programs with different addressing 
modes. In the example, TEST executes in 24-bit AMODE and EP1 executes in 31 -bit 
AMODE. Before transferring control to EP1, the TEST program loads register 15 with EPA, 
the pointer defined entry point address (that is, the address of EP1 with the high order bit set to 
1 to indicate 31 -bit AMODE). This is followed by a BASSM 14,15 instruction, which performs 
the following functions: 

• Sets the high-order bit of the link register (register 14) to (because TEST is currently 
executing in 24-bit AMODE) and puts the address of the next sequential instruction into 
bits 1-31. 

• Sets the PSW AMODE bit to 1 to agree with bit of register 15. 

• Transfers to EP1 (the address in bits 1-31 of register 15). 
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The EP1 program executes in 31 -bit AMODE. Upon completion, EP1 sets a return code in 
register 15 and executes a BSM 0,14 instruction, which performs the following functions: 

• Sets the PSW AMODE bit to to correspond to the high-order bit of register 14. 

• Transfers control to the address following the BASSM instruction in the TEST program. 
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TEST 


CSECT 




TEST 


AMODE 


24 


TEST 


RMODE 


24 




L 


15, EPA 




BASSM 


14,15 



OBTAIN TRANSFER ADDRESS 
SWITCH AMODE AND TRANSFER 



EPA 



EXTRN EP1 

DC A (X' 80000000 '+EP1) POINTER DEFINED ENTRY POINT ADDRESS 



END 



EP1 


CSECT 




EP1 


AMODE 


31 


EP1 


RMODE 


ANY 




SLR 


15,15 




BSM 


0,14 




END 





t 



SET RETURN CODE 

RETURN TO CALLER'S AMODE AND TRANSFER 



Figure 8. Example of Addressing Mode Switch 



Load Module Structure Types 



Each load module used during a job step can be designed in one of three load module 
structures: simple, planned overlay, or dynamic. A simple structure does not pass control to any 
other load modules during its execution, and is brought into virtual storage all at one time. A 
planned overlay structure may, if necessary, pass control to other load modules during its 
execution, and it is not brought into virtual storage all at one time. Instead, segments of the 
load module reuse the same area of virtual storage. A dynamic structure is brought into virtual 
storage all at one time, and passes control to other load modules during its execution. Each of 
the load modules to which control is passed can be one of the three structure types. 
Characteristics of the load module structure types are summarized in Figure 9. 

Since the large capacity of virtual storage all but eliminates the need for complex overlay 
structures, planned overlays will not be discussed further. 
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Passes Control to Other 
Structure Type Loaded All at One Time Load Modules 

Simple Yes No 

Planned Overlay No Optional 

Dynamic Yes Yes 



Figure 9. Characteristics of Load Modules 



Simple Structure 



A simple structure consists of a single load module produced by the linkage editor. The single 
load module contains all of the instructions required and is paged into real storage by the 
control program as it is executed. The simple structure can be the most efficient of the two 
structure types because the instructions it uses to pass control do not require control-program 
assistance. However, you should design your program to make most efficient use of paging. 



Dynamic Structure 
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A dynamic structure requires more than one load module during execution. Each load module 
required can operate as either a simple structure or another dynamic structure. The advantages 
of a dynamic structure over a simple structure increase as the program becomes more complex, 
particularly when the logical path of the program depends on the data being processed. The 
load modules required in a dynamic structure are paged into real storage when required, and 
can be deleted from virtual storage when their use is completed. 



Load Module Execution 



Depending on the configuration of the operating system and the macro instructions used to 
pass control, execution of the load modules is serial or in parallel. Execution is serial in the 
MVS/XA operating system unless an ATTACH macro instruction is used to create a new task. 
The new task competes for processor time independently with all other tasks in the system. The 
load module named in the ATTACH macro instruction is executed in parallel with the load 
module containing the ATTACH macro instruction. The execution of the load modules is 
serial within each task. 

The following paragraphs discuss passing control for serial execution of a load module. 
Creation and management of new tasks is discussed under the headings "Task Creation and 
Control." 



Passing Control in a Simple Structure 



There are certain procedures to follow when passing control to' an entry point in the same load 
module. The established conventions to use when passing control are also discussed. These 
procedures and conventions are the framework for all program interfaces. Knowledge of the 
information about addressing contained in the Assembler Language publication is required. 
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Passing Control without Return 



Some control sections pass control to another control section of the load module and do not ^ 

receive control back. An example of this type of control section is a housekeeping routine at 
the beginning of a program that establishes values, initializes switches, and acquires buffers for 
the other control sections in the program. Use the following procedures when passing control 
without return. 

Preparing to Pass Control 

Because control will not be returned to this control section, you must restore the contents of 
register 14. Register 14 originally contained the address of the location in the calling program 
(for example, the control program) to which control is to be passed when your program is 
finished. Since the current control section does not make the return to the calling program, the 
return address must be passed on to the control section that does make the return. In addition, 
the contents of registers 2-12 must be unchanged when your program eventually returns control, 
so these registers must also be restored. 

If control were being passed to the next entry point from the control program, register 15 
would contain the entry address. You should use register 15 in the same way, so that the called 
routine remains independent of the program that passed control to it. 

Use register 1 to pass parameters. Establish a parameter list and place the address of the list in 

register 1 . The parameter list should consist of consecutive fullwords starting on a fullword 

boundary, each fullword containing an address to be passed to the called control section. 

When executing in 24-bit AMODE, each address is located in the three low-order bytes of the 

word. When executing in 31 -bit AMODE, each address is located in bits 1-31 the word. In a 

both addressing modes, set the high-order bit of the last word to 1 to indicate that it is the last \ 

word of the list. The system convention is that the list contain addresses only. You may, of 

course, deviate from this convention; however, when you deviate from any system convention, 

you restrict the use of your programs to those programmers who know about your special 

conventions. 

Since you have reloaded all the necessary registers, the save area that you received on entry is 
now available, and should be reused by the called control section. Pass the address of the save 
area in register 13 just as it was passed to you. By passing the address of the old save area, you 
save the 72 bytes of virtual storage for a second, unnecessary, save area. 

Note: If you pass a new save area instead of the one received on entry, errors could occur. 

Passing Control 

The common way to pass control between one control section and an entry point in the same 
load module is to load register 15 with a V-type address constant for the name of the external 
entry point, and then to branch to the address in register 15. The external entry point must 
have been identified using an ENTRY instruction in the called control section if the entry point 
is not the same as the control section's CSECT name. 

Figure 10 shows an example of loading registers and passing control. In this example, no new 

save area is used, so register 13 still contains the address of the old save area. It is also 

assumed for this example that the control section will pass the same parameters it received to 

the next entry point. First, register 14 is reloaded with the return address. Next, register 15 is . 

loaded with the address of the external entry point NEXT, using the V-type address constant at I 

the location NEXTADDR. Registers 0-12 are reloaded, and control is passed by a branch 
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instruction using register 15. The control section to which control is passed contains an 
ENTRY instruction identifying the entry point NEXT. 



L 14,12(13) 

L 15,NEXTADDR 

LM 0,12,20(13) 

BR 15 



LOAD CALLER'S RETURN ADDRESS 
ENTRY NEXT 

RETURN CALLER'S REGISTERS 
NEXT SAVE (14,12) 



NEXTADDR DC V(NEXT) 



Figure 10. Passing Control in a Simple Structure 

Figure 1 1 shows an example of passing a parameter list to an entry point with the same 
addressing mode. Early in the routine the contents of register 1 (that is, the address of the 
fullword containing the PARM field address) were stored at the fullword P ARM ADD R. 
Register 13 is loaded with the address of the old save area, which had been saved in word 2 of 
the new save area. The contents of register 14 are restored, and register 15 is loaded with the 
entry address. 



jr 



EARLY 



USING *,12 

ST 1 , PARMADDR 



Establish addressability 
Save parameter address 



L 13,4(13) 

L 0,20(13) 

L 14,12(13) 

L 15, NEXTADDR 

LA 1,PARMLIST 

OI PARMADDR,X'80' 

LM 2,12,28(13) 

BR 15 



Reload address of old save area 

Load return address 
Load address of next entry point 
Load address of parameter list 
Turn on last parameter indicator 
Reload remaining registers 
Pass control 



PARMLIST DS 
DCBADDRS DC 
DC 
PARMADDR DC 
NEXTADDR DC 



0A 

A(INDCB) 

A(OUTDCB) 

A(0) 

V(NEXT) 



Figure 11. Passing Control With a Parameter List 
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The address of the list of parameters is loaded into register 1 . These parameters include the 
addresses of two data control blocks (DCBs) and the original register 1 contents. The 
high-order bit in the last address parameter (PARMADDR) is set to 1 using an OR-immediate 
instruction. The contents of registers 2-12 are restored. (Since one of these registers was the 
base register, restoring the registers earlier would have made the parameter list unaddressable.) 
A branch register instruction using register 15 passes control to entry point NEXT. 
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Passing Control with Return 



The control program passed control to your program, and your program will return control 
when it is through processing. Similarly, control sections within your program will pass control 
to other control sections, and expect to receive control back. An example of this type of 
control section is a monitoring routine; the monitor determines the order of execution of other 
control sections based on the type of input data. Use the following procedures when passing 
control with return. 



Preparing to Pass Control 



Use registers 15 and 1 in the same manner they are used to pass control without return. 
Register 15 contains the entry address in the new control section and register 1 is used to pass a 
parameter list. 

Register 14 must contain the address of the location to which control is to be returned when the 
called control section completes execution. The address can be the instruction following the 
instruction which causes control to pass, or it can be another location within the current control 
section designed to handle all returns. Registers 2-12 are not involved in the passing of control; 
the called control section should not depend on the contents of these registers in any way. 

You should provide a new save area for use by the called control section as previously 
described, and pass the address of that save area in register 13. Note that the same save area 
can be reused after control is returned by the called control section. One new save area is 
ordinarily all you will require regardless of the number of control sections called. 



Passing Control 



Two standard methods are used for passing control to another control section and providing 
for return of control. One is an extension of the method used to pass control without a return, 
and requires a V-type address constant and a branch, a branch and link, or a branch and save 
instruction provided both programs execute in the same addressing mode. If the addressing 
mode changes, a branch and save and set mode instruction should be used. The other method 
uses the CALL macro instruction to provide a parameter list and establish the entry and return 
addresses. With either method, you must identify the entry point by an ENTRY instruction in 
the called control section if the entry name is not the same as the control section CSECT name. 
Figure 12 and Figure 13 illustrate the two methods of passing control; in each example, assume 
that register 13 already contains the address of a new save area. 

Figure 12 also shows the use of an inline parameter list and an answer area. The address of 
the external entry point is loaded into register 1 5 in the usual manner. A branch and link 
instruction is then used to branch around the parameter list and to load register 1 with the 
address of the parameter list. An inline parameter list, such as the one shown in Figure 12, is 
convenient when you are debugging because the parameters involved are located in the listing 
(or the dump) at the point they are used, instead of at the end of the listing or dump. Note 
that the high-order bit of the last address parameter (ANSWERAD) is set to 1 to indicate the 
end of the list. The area pointed to by the address in the ANSWERAD parameter is an area to 
be used by the called control section to pass parameters back to the calling control section. 
This is a possible method to use when a called control section must pass parameters back to the 
calling control section. Parameters are passed back in this manner so that no additional 
registers are involved. The area used in this example is twelve words. The size of the area for 
any specific application depends on the requirements of the two control sections involved. 



( 
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Entry address in register 15 

Parameter list address in 
register 1 

Start of parameter list 
Input DCB address 
Output DCB address 
Answer area address with 
high-order bit on 
Address of entry point 
Pass control; register 14 
contains return address 
and current AMODE 

Answer area from NEXT 

Note: This example assumes that you are passing control to a program that executes in the same addressing mode as 
your program. See the topic "Linkage Considerations for MVS/XA" for information on how to handle branches 
between programs that execute in different addressing modes. 
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Figure 12. Passing Control With Return 






RETURNPT 
AREA 



CALL NEXT , ( INDCB , OUTDCB , AREA ) , VL 
DC 12F'0 I 



Note: You cannot use the CALL macro instruction to pass control to a program that executes in a different addressing 
mode. 



Figure 13. Passing Control With CALL 

The CALL macro instruction in Figure 13 provides the same functions as the instructions in 
Figure 12. When the CALL macro instruction is expanded, the parameters cause the following 
results: 

NEXT - A V-type address constant is created for NEXT, and the address is loaded into 
register 15. 

(INDCB,OUTDCB,AREA) - A-type address constants are created for the three parameters 
coded within parentheses, and the address of the first A-type address constant is placed in 
register 1. 

VL - The high-order bit of the last A-type address constant is set to 1. 

Control is passed to NEXT using a branch and link instruction. The address of the instruction 
following the CALL macro instruction is loaded into register 14 before control is passed. 



) 



In addition to the results described above, the V-type address constant generated by the CALL 
macro instruction requires the load module with the entry point NEXT to be link edited into 
the same load module as the control section containing the CALL macro instruction. The 
Linkage Editor and Loader publication tells more about this service. 
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The parameter list constructed from the CALL macro instruction in Figure 13, contains only 
A-type address constants. A variation on this type of parameter list results from the following 
coding: 

CALL NEXT, (INDCB,(6) ,(7)) ,VL 

In the above CALL macro instruction, two of the parameters to be passed are coded as 
registers rather than symbolic addresses. The expansion of this macro instruction again results 
in a three-word parameter list; in this example, however, the expansion also contains 
instructions that store the contents of registers 6 and 7 in the second and third words, 
respectively, of the parameter list. The high-order bit in the third word is set to 1 after register 
7 is stored. You can specify as many address parameters as you need, and you can use 
symbolic addresses or register contents as you see fit. 



Analyzing the Return 



When control is returned from the control program after processing a non-authorized system 
macro instruction, the contents of registers 2-13 are unchanged. When control is returned to 
your control section from the called control section, registers 2-14 contain the same information 
they contained when control was passed, as long as system conventions are followed. The 
called control section has no obligation to restore registers and 1; so the contents of these 
registers may or may not have been changed. 

When control is returned, register 15 can contain a return code indicating the results of the 

processing done by the called control section. If used, the return code should be a multiple of 

four, so a branching table can be used easily, and a return code of zero should be used to 

indicate a normal return. The control program frequently uses this method to indicate the . 

results of the requests you make using system macro instructions; an example of the type of (J 

return codes the control program provides is shown in the description of the IDENTIFY macro 

instruction. 

The meaning of each of the codes to be returned must be agreed upon in advance. In some 
cases, either a "good" or "bad" indication (zero or nonzero) will be sufficient for you to decide 
your next action. If this is true, the coding in Figure 14 could be used to analyze the results. 
Many times, however, the results and the alternatives are more complicated, and a branching 
table, such as shown in Figure 15 could be used to pass control to the proper routine. 

Note: Explicit tests are required to ensure that the return code value does not exceed the 
branch table size. 



RETURNPT LTR 15,15 Test return code for zero 

BNZ ERRORTN Branch if not zero to error 
routine 



Figure 14. Test for Normal Return 



( 
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CONDI 
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COND2 
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GIVEUP 



Branch to table using return 

code 

Branch to normal routine 

Branch to routine for 

condition 1 

Branch to routine for 

condition 2 

Branch to routine to handle 

impossible situations 



Figure 15. Return Code Test Using Branching Table 



How Control is Returned 



In the discussion of the return under "Analyzing the Return" it was indicated that the control 
section returning control must restore the contents of registers 2-14. Because these are the same 
registers reloaded when control is passed without a return, refer to the discussion under 
"Passing Control without Return" for detailed information and examples. The contents of 
registers and 1 do not have to be restored. 

Register 15 can contain a return code when control is returned. As indicated previously, a 
return code should be a multiple of four with a return code of zero indicating a normal return. 
The return codes other than zero that you use can have any meaning, as long as the control 
section receiving the return codes is aware of that meaning. 

The return address is the address originally passed in register 14; you should always return 
control to that address. If an addressing mode switch is not involved, you can either use a 
branch instruction such as BR 14, or you can use the RETURN macro instruction. An 
example of each of these methods of returning control is discussed in the following paragraphs. 
If an addressing mode switch is involved, you can use a BSM 0,14 instruction to return control. 
See Figure 8 for an example that uses the BSM instruction to return control. 

Figure 16 shows a portion of a control section used to analyze input data cards and to check 
for an out-of-tolerance condition. Each time an out-of-tolerance condition is found, in addition 
to some corrective action, one is added to the one-byte value at the address STATUSBY. After 
the last data card is analyzed, this control section returns to the calling control section, which 
bases its next action on the number of out-of-tolerance conditions encountered. The coding 
shown in Figure 16 loads register 14 with the return address. The contents of register 15 are 
set to zero, and the value at the address STATUSBY (the number of errors) is placed in the 
low-order eight bits of the register. The contents of register 15 are shifted to the left two places 
to make the value a multiple of four. Registers 2-12 are reloaded, and control is returned to 
the address in register 14. 
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L 13,4(13) Load address of previous save 

area 
L 14,12(13) Load return address 
SR 15,15 Set register 15 to zero 
IC 15,STATUSBY Load number of errors 
SLA 15,2 Set return code to multiple 

of 4 
LM 2,12,28(13) Reload registers 2-12 
BR 14 Return 



STATUSBY DC X ' 00 ' 

Note: This example assumes that you are returning to a program with the same AMODE. If not, use the BSM 
instruction to transfer control. 



Figure 16. Establishing a Return Code 

The RETURN macro instruction saves coding time. The expansion of the RETURN macro 
instruction provides instructions that restore a designated range of registers, load a return code 
in register 15, and branch to the address in register 14. If T is specified, the RETURN macro 
instruction flags the save area used by the returning control section (that is, the save area 
supplied by the calling routine). It does this by setting the low-order bit of word four of the 
save area to one after the registers have been restored. The flag indicates that the control 
section that used the save area has returned to the calling control section. The flag is useful 
when tracing the flow of your program in a dump. For a complete record of program flow, a 
separate save area must be provided by each control section each time control is passed. 

You must restore the contents of register 13 before issuing the RETURN macro instruction. 
Code the registers to be reloaded in the same order as they would have been designated for a 
load-multiple (LM) instruction. You can load register 15 with the return code before you write 
the RETURN macro instruction, you can specify the return code in the RETURN macro 
instruction, or you can reload register 15 from the save area. 

The coding shown in Figure 17 provides the same result as the coding shown in Figure 16. 
Registers 13 and 14 are reloaded, and the return code is loaded in register 15. The RETURN 
macro instruction reloads registers 2-12 and passes control to the address in register 14. The 
save area used is not flagged. The RC = (15) parameter indicates that register 15 already 
contains the return code, and the contents of register 15 are not to be altered. 



( 
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Reload registers and 
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STATUSBY DC 



X'OO' 



Note: You cannot use the RETURN macro instruction to pass control to a program that executes in a different 
addressing mode. 



Figure 17. Using the RETURN Macro Instruction 



X 



Figure 18 illustrates another use of the RETURN macro instruction. The correct save area 
address is again established, and then the RETURN macro instruction is issued. In this 
example, registers 14 and 0-12 are reloaded, a return code of 8 is placed in register 15, the save 
area is flagged, and control is returned. Specifying a return code overrides the request to 
restore register 15 even though register 15 is within the designated range of registers. 



L 13,4(13) 

RETURN (14,12) ,T,RC=8 



Figure 18. RETURN Macro Instruction With Flag 



Return to the Control Program 



■ 
M 

inr 



The discussion in the preceding paragraphs has covered passing control within one load 
module, and has been based on the assumption that the load module was brought into virtual 
storage because of the program name specified in the EXEC statement. The control program 
established only one task to be performed for the job step. When the logical end of the 
program is reached, control passes to the return address passed (in register 14) to the first 
control section in the control program. When the control program receives control at this 
point, it terminates the task it created for the job step, compares the return code in register 15 
with any COND values specified on the JOB and EXEC statements, and determines whether or 
not subsequent job steps, if any are present, should be executed. 
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Passing Control in a Dynamic Structure 



The discussion of passing control in a simple structure provides the background for the 
discussion of passing control in a dynamic structure. Within each load module, control should 
be passed as in a simple structure. If you can determine which control sections will make up a 
load module before you code the control sections, you should pass control within the load 
module without involving the control program. The macro instructions discussed in this section 
provide increased linkage capability, but they require control program assistance and possibly 
increased execution time. 

Bringing the Load Module into Virtual Storage 

The load module containing the entry name you specified on the EXEC statement is 
automatically brought into virtual storage by the control program. The control program places 
the load module above or below 16 Mb according to its RMODE attribute. Any other load 
modules you require during your job step are brought into virtual storage by the control 
program when requested; these requests are made by using the LOAD, LINK, ATTACH, and 
XCTL macro instructions. The LOAD macro instruction sets the high-order bit of the entry 
point address to indicate the addressing mode of the load module. The ATTACH, LINK, and 
XCTL macro instructions use this information to set the addressing mode for the module that 
gets control. If the AMODE is ANY, the module will get control in the same addressing mode 
as the program that issued the ATTACH, LINK, or XCTL macro instruction. If a copy of the 
load module must be brought into storage, the control program places the load module above 
or below 16 Mb according to its RMODE attribute. The following paragraphs discuss the 
proper use of these macro instructions. 

Location of the Load Module 

Initially, each load module that you can obtain dynamically is located in a library (partitioned 
data set). This library is the link library, the job or step library, the task library, or a private 
library. 

• The link library is always present and is available to all job steps of all jobs. The control 
program provides the data control block for the library and logically connects the library to 
your program, making the members of the library available to your program. 

• The job and step libraries are explicitly established by including //JOBLIB and //STEPLIB 
DD statements in the input stream. The //JOBLIB DD statement is placed immediately 
after the JOB statement, while the //STEPLIB DD statement is placed among the DD 
statements for a particular job step. The job library is available to all steps of your job, 
except those that have step libraries. A step library is available to a single job step; if there 
is a job library, the step library replaces the job library for the step. For either the job 
library or the step library, the control program provides the data control block and issues 
the OPEN macro instruction to logically connect the library to your program. 

• Unique task libraries can be established by using the TASKLIB parameter of the ATTACH 
macro instruction. The issuer of the ATTACH macro instruction is responsible for 
providing the DD statement and opening the data set or sets. If the TASKLIB parameter 
is omitted, the task library of the attaching task is propagated to the attached task. In the 
following example, task A's job library is LIB1. Task A attaches task B, specifying 
TASKLIB = LIB2 in the ATTACH macro instruction. Task B's task library is 
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therefore LIB2. When task B attaches task C, LIB2 is searched for task C before LIB1 or 
the link library. Because task B did not specify a unique task library for task C, its own 
task library (LIB2) is propagated to task C and is the first library searched when task C 
requests that a module be brought into virtual storage. 

Task A ATTACH EP=B / TASKLIB=LIB2 
Task B ATTACH EP=C 

• A private library is defined by including a DD statement in the input stream and is 
available only to the job step in which it is defined. You must provide the data control 
block and issue the OPEN macro instruction for each data set. You may use more than 
one private library by including more than one DD statement and an associated data 
control block. 

A library can be a single partitioned data set, or a collection of such data sets. When it is a 
collection, you define each data set by a separate DD statement, but you assign a name only to 
the statement that defines the first data set. Thus, a job library consisting of three partitioned 
data sets would be defined as follows: 



//JOBLIB 


DD 


DSNAME=PDS 1 , . . 


// 


DD 


DSNAME=PDS2, . . 


// 


DD 


DSNAME=PDS3. . . 



) 



The three data sets (PDS1, PDS2, PDS3) are processed as one, and are said to be concatenated. 
Concatenation and the use of partitioned data sets is discussed in more detail in the Data 
Management Services publication. 

Some of the load modules from the link library may already be in virtual storage in an area 
called the link pack area. The contents of these areas are determined during the nucleus 
initialization process and will vary depending on the requirements of your installation. The link 
pack area contains all reenterable load modules from the LPA library, along with installation 
selected modules from the SVC and link libraries. These load modules can be used by any job 
step in any job. 

With the exception of those load modules contained in this area, copies of all of the reenterable 
load modules you request are brought into your area of virtual storage and are available to any 
task in your job step. The portion of your area containing the copies of the load modules is 
called the job pack area. 



The Search for the Load Module 



X 



In response to your request for a copy of a load module, the control program searches the job 
pack area, the task's load list, and the link pack area. If a copy of the load module is found in 
one of the pack areas, the control program determines whether that copy can be used (see 
"Using an Existing Copy"). If an existing copy can be used, the search stops. If it cannot be 
used, the search continues until the module is located in a library. The load module is then 
brought into the job pack area or the load list area. 

The order in which the libraries and pack areas are searched depends on the parameters used in 
the macro instruction (LINK, LOAD, XCTL, or ATTACH) requesting the load module. The 
parameters that define the order of the search are EP, EPLOC, DE, DCB, and TASKLIB. 

The TASKLIB parameter is used only for ATTACH. You should choose the parameters for the 
macro instruction that provide the shortest search time. The search of a library actually involves 
the search of a directory, followed by copying the directory entry into virtual storage, followed 
by loading the load module into virtual storage. If you know the location of the load module, 
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you should use parameters that eliminate as many of these searches as possible, as indicated in 
Figure 19, Figure 20, and Figure 21. 

The EP, EPLOC, or DE parameter specifies the name of the entry point in the load module; 
you code one of the three every time you use a LINK, LOAD, XCTL, or ATTACH macro 
instruction. The optional DCB parameter indicates the address of the data control block for 
the library containing the load module. Omitting the DCB parameter or using the DCB 
parameter with an address of zero specifies the data control block for the task libraries, the job 
or step library, or the link library. If TASKLIB is specified and if the DCB parameter contains 
the address of the data control block for the link library, no other library is searched. 

To avoid using "system copies" of modules resident in LPA and LINKLIB, you can specifically 
limit the search for the load module to the job pack area and the first library on the normal 
search sequence, by specifying the LSEARCH parameter on the LINK, LOAD, or XCTL 
macro instruction with the DCB for the library to be used. 

The following paragraphs discuss the order of the search when the entry name used is a member 
name. 

The EP and EPLOC parameters require the least effort on your part; you provide only the 
entry name, and the control program searches for a load module having that entry name. 
Figure 19 shows the order of the search when EP or EPLOC is coded, and the DCB parameter 
is omitted or DCB = is coded. 



The job pack area is searched for an available copy. 

The requesting task's task library and all the unique task libraries of its preceding tasks are searched. (Note: For the 
ATTACH macro, the attached task's library and all the unique task libraries of its preceding tasks are searched.) 
The step library is searched; if there is no step library, the job library (if any) is searched. 
The link pack area is searched. 
The link library is searched. 



Figure 19. Search for Module, EP or EPLOC Parameter With DCB = or DCB Parameter Omitted 

When used without the DCB parameter, the EP and EPLOC parameters provide the easiest 
method of requesting a load module from the link, job, or step library. The task libraries are 
searched before the job or step library, beginning with the task library of the task that issued 
the request and continuing through the task libraries of all its antecedent tasks. The job or step 
library is then searched, followed by the link library. 

A job, step, or link library or a data set in one of these libraries can be used to hold one version 
of a load module, while another can be used to hold another version with the same entry name. 
If one version is in the link library, you can ensure that the other will be found first by 
including it in the job or step library. However, if both versions are in the job or step library, 
you must define the data set that 

contains the version you want to use before the data set that contains the other version. For 
example, if the wanted version is in PDS1 and the unwanted version is in PDS2, a step library 
consisting of these data sets should be defined as follows: 

//STEPLIB DD DSNAME=PDS1, . . . 
// DD DSNAME=PDS2 , . . . 

If, however, the first version of a nonreusable module in the job or step library has been 
previously loaded and the version in the link library or the second version in the job library is 
desired, the DCB parameter must be coded in the macro instructions. 



< 



< 
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Use extreme caution when specifying module names in unique task libraries, because duplicate 
names may cause the wrong module to be brought into virtual storage when a task requests it. 
Once a module has been loaded from a task library, the module name is known to all tasks in 
the region and a copy of that module is given to all tasks requesting that that module name be 
loaded, regardless of the requester's task library. 

If you know that the load module you are requesting is a member of one of the private 
libraries, you can still use the EP or EPLOC parameter, this time in conjunction with the DCB 
parameter. You specify the address of the data control block for the private library in the DCB 
parameter. The order of the search for EP or EPLOC with the DCB parameter is shown in 
Figure 20. 

The job pack area is searched for an available copy. 
The specified library is searched. 
The link pack area is searched. 
The link library is searched. 



Figure 20. Search for Module, EP or EPLOC Parameters With DCB Parameter Specifying Private 
Library 

Searching a job or step library slows the retrieval of load modules from the link library; to 
speed this retrieval, you should limit the size of the job and step libraries. You can best do this 
by eliminating the job library altogether and providing step libraries where required. You can 
limit each step library to the data sets required by a single step; some steps (such as 
compilation) do not require a step library and therefore do not require searching and retrieving 
modules from the link library. For maximum efficiency, you should define a job library only 
when a step library would be required for every step, and every step library would be the same. 

The DE parameter requires more work than the EP and EPLOC parameters, but it can reduce 
the amount of time spent searching for a load module. Before you can use this parameter, you 
must use the BLDL macro instruction to obtain the directory entry for the module. The 
directory entry is part of the library that contains the module. 

To save time, the BLDL macro instruction must obtain directory entries for more than one 
entry name. You specify the names of the load modules and the address of the data control 
block for the library when using the BLDL macro instruction; the control program places a 
copy of the directory entry for each entry name requested in a designated location in virtual 
storage. If you specify the link library and the job or step library, the directory information 
indicates from which library the directory entry was taken. The directory entry always indicates 
the relative track and block location of the load module in the library. If the load module is 
not located on the library you indicate, a return code is given. You can then issue another 
BLDL macro instruction specifying a different library. 

To use the DE parameter, you provide the address of the directory entry and code or omit the 
DCB parameter to indicate the same library specified in the BLDL macro instruction. The task 
using the DE parameter should be the same as the one which issued the BLDL or one which 
has the same job, step, and task library structure as the task issuing the BLDL. The order of 
the search when the DE parameter is used is shown in Figure 21 for the link, job, step, and 
private libraries. 

The preceding discussion of the search is based on the premise that the entry name you 
specified is the member name. The control program checks for an alias entry point name when 
the load module is found in a library. If the name is an alias, the control program obtains the 
corresponding member name from the library directory, and then searches to determine if a 
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usable copy of the load module exists in the job pack area. If a usable copy does not exist in a 
pack area, a new copy is brought into the job pack area. Otherwise, the existing copy is used, 
conserving virtual storage and eliminating the loading time. 

Directory Entry Indicates Link Library and DCB = or DCB Parameter Omitted. 

The job pack area for the region is searched for an available copy. 

The link pack area is searched. 

The module is obtained from the link library. 
Directory Entry Indicates Job, Step, or Task Library and DCB = or DCB Parameter Omitted. 

The job pack area for the region is searched for an available copy. 

The module is obtained from the task library designated by the 'Z' byte of the DE operand. 
DCB Parameter Indicates Private Library 

The job pack area for the region is searched for an available copy. 

The module is obtained from the specified private library. 



Figure 21. Search for Module Using DE Parameter 

As the discussion of the search indicates, you should choose the parameters for the macro 
instruction that provide the shortest search time. The search of a library actually involves a 
search of the directory, followed by copying the directory entry into virtual storage, followed by 
loading the load module into virtual storage. If you know the location of the load module, you 
should use the parameters that eliminate as many of these unnecessary searches as possible, as 
indicated in Figure 19, Figure 20, and Figure 21. Examples of the use of these figures are 
shown in the following discussion of passing control. 



Using an Existing Copy 



The control program uses a copy of the load module already in the job pack area if the copy 

can be used. Whether the copy can be used or not depends on the reusability and current A 

status of the load module; that is, the load module attributes, as designated using linkage editor ^ 

control statements, and whether the load module has already been used or is in use. The status 

information is available to the control program only when you specify the load module entry 

name on an EXEC statement, or when you use ATTACH, LINK, or XCTL macro instructions 

to transfer control to the load module. The control program protects you from obtaining an 

unusable copy of a load module if you always "formally" request a copy using these macro 

instructions (or the EXEC statement); if you pass control in any other manner (for instance, a 

branch or a CALL macro instruction), the control program, because it is not informed, cannot 

protect your copy. 

All reenterable modules (modules designated as reenterable using the linkage editor) from any 
library are completely reusable; only one copy is ever placed in the link pack area or brought 
into your job pack area, and you get immediate control of the load module. If the module is 
serially reusable, only one copy is ever placed in the job pack area; this copy is always used for 
a LOAD macro instruction. If the copy is in use, however, and the request is made using a 
LINK, ATTACH, or XCTL macro instruction, the task requiring the load module is placed in 
a wait condition until the copy is available. A LINK macro instruction should not be issued 
for a serially reusable load module currently in use for the same task; the task will be 
abnormally terminated. (This could occur if an exit routine issued a LINK macro instruction 
for a load module in use by the main program.) 

If the load module is not reusable, a LOAD macro instruction will always bring in a new copy 
of the load module; an existing copy is used only if a LINK, ATTACH, or XCTL macro 
instruction is issued and the copy has not been used previously. Remember, the control 
program can determine if a load module has been used or is in use only if all of your requests 
are made using LINK, ATTACH, or XCTL macro instructions. 



32 Supervisor Services and Macro Instructions 



( 



Using the LOAD Macro Instruction 



The LOAD macro instruction is used to ensure that a copy of the specified load module is in 
virtual storage in your region or job pack area if it was not preloaded into the link pack area. 
When a LOAD macro instruction is issued, the control program searches for the load module 
as discussed previously and brings a copy of the load module into the region if required. When 
the control program returns control, register contains the addressing mode and the virtual 
storage address of the entry point specified for the requested load module, and register 1 
contains the length of the loaded module (in doublewords) and the authorization code in the 
high byte. Normally, the LOAD macro instruction is used only for a reenterable or serially 
reusable load module, since the load module is retained even though it is not in use. 

The control program also establishes a "responsibility" count for the copy, and adds one to the 
count each time the requirements of a LOAD macro instruction are satisfied by the same copy. 
As long as the responsibility count is not zero, the copy is retained in virtual storage. 

The responsibility count for the copy is lowered by one when a DELETE macro instruction is 
issued during the task which was active when the LOAD macro instruction was issued. When a 
task is terminated, the count is lowered by the number of LOAD macro instructions issued for 
the copy when the task was active minus the number of deletions. When the use count for a 
copy in a job pack area reaches zero, the virtual storage area containing the copy is made 
available. 
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The LINK macro instruction is used to pass control between load modules and to provide for 
return of control. You can also pass control using branch, branch and link, branch and save, 
or branch and save and set mode instructions or the CALL macro instruction; however, when 
you pass control in this manner you must protect against multiple uses of nonreusable or 
serially reusable modules. You must also be careful to enter the routine in the proper 
addressing mode. The following paragraphs discuss the requirements for passing control with 
return in each case. 



The LINK Macro Instruction 
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When you use the LINK macro instruction, as far as the logic of your program is concerned, 
you are passing control to another load module. Remember, however, that you are requesting 
the control program to assist you in passing control. You are actually passing control to the 
control program, using an SVC instruction, and requesting the control program to find a copy 
of the load module and pass control to the entry point you designate. There is some similarity 
between passing control using a LINK macro instruction and passing control using a CALL 
macro instruction in a simple structure. These similarities are discussed first. 

The convention regarding registers 2-12 still applies; the control program does not change the 
contents of these registers, and the called load module should restore them before control is 
returned. You must provide the address in register 13 of the save area for use by the called 
load module; the control program does not use this save area. You can pass address 
parameters in a parameter list to the load module using register 1; the LINK macro instruction 
provides the same facility for constructing this list as the CALL macro instruction. Register 
is used by the control program and the contents may be modified. In certain cases, the contents 
of register 1 may be altered by the LINK macro instruction. 

There is also some difference between passing control using a LINK macro instruction and 
passing control using a CALL macro instruction. When you pass control in a simple structure, 
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register 15 contains the entry address and register 14 contains the return address. When the 
called load module gets control, that is still what registers 14 and 15 contain, but when you use 
the LINK macro instruction, it is the control program that establishes these addresses. When 
you code the LINK macro instruction, you provide the entry name and possibly some library 
information using the EP, EPLOC, or DE, and DCB parameters, but you have to get this entry 
name and library information to the control program. The expansion of the LINK macro 
instruction does this by creating a control program parameter list (the information required by 
the control program) and passing its address to the control program. After the control program 
finds the entry name, it places the address in register 15. 

The return address in your control section is always the instruction following the LINK; that is 
not, however, the address that the called load module receives in register 14. The control 
program saves the address of the location in your program in its own save area, and places in 
register 14 the address of a routine within the control program that will receive control. 
Because control was passed using the control program, return must also be made using the 
control program. The control program also handles all switching of addressing mode when 
processing the LINK macro instruction. 

The control program establishes a use count for a load module when control is passed using the 
LINK macro instruction. This is a separate use count from the count established for LOAD 
macro instructions, but it is used in the same manner. The count is increased by one when a 
LINK macro instruction is issued and decreased by one when return is made to the control 
program or when the called load module issues an XCTL macro instruction. 

Figure 22 and Figure 23 show the coding of a LINK macro instruction used to pass control to 
an entry point in a load module. In Figure 22, the load module is from the link, job, or step 
library; in Figure 23, the module is from a private library. Except for the method used to pass 
control, this example is similar to Figures 10 and 11. A problem program parameter list 
containing the addresses INDCB, OUTDCB, and AREA is passed to the called load module; 
the return point is the instruction following the LINK macro instruction. A V-type address 
constant is not generated, because the load module containing the entry point NEXT is not to 
be edited into the calling load module. Note that the EP parameter is chosen, since the search 
begins with the job pack area and the appropriate library as shown in Figure 19. 



LINK EP=NEXT , PARAM= ( INDCB, OUTDCB, AREA) ,VL=1 
RETURNPT 
AREA DC 12F'0' 



Figure 22. Use of the LINK Macro Instruction With the Job or Link Library 
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OPEN 



(PVTLIB) 



LINK EP=NEXT , DCB=PVTLIB , PARAM= ( INDCB , OUTDCB , 
AREA) ,VL=1 



PVTLIB 



DCB 



DDNAME=PVTLIBDD , DSORG=PO , MACRF= ( R ) 



Figure 23. Use of the LINK Macro Instruction With a Private Library 

Figure 24 and Figure 25 show the use of the BLDL and LINK macro instructions to pass 
control. Assuming that control is to be passed to an entry point in a load module from the link 
library, a BLDL macro instruction is issued to bring the directory entry for the member into 
virtual storage. (Remember, however, that time is saved only if more than one directory entry 
is requested in a BLDL macro instruction. Only one is requested here for simplicity.) 
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Figure 24. Use of the BLDL Macro Instruction 

The first parameter of the BLDL macro instruction is a zero, which indicates that the directory 
entry is on the link, job, step, or task library. The second parameter is the address in virtual 
storage of the list description field for the directory entry. The second two bytes at 
LISTADDR indicate the length of each entry. A character constant is established to contain 
the directory information to be placed there by the control program as a result of the BLDL 
macro instruction. The LINK macro instruction in Figure 25 can now be written. Note that 
the DE parameter refers to the name field, not the list description field, of the directory entry. 



LINK 



DE=NAMEADDR , DCB=0 , P ARAM= ( INDCB , OUTDCB , AREA ) , VL= 1 



J 



Figure 25. The LINK Macro Instruction With a DE Parameter 
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Using CALL or Branch and Link 

You can save time by passing control to a load module without using the control program. ' 

Passing control without using the control program is performed as follows. Issue a LOAD 

macro instruction to obtain a copy of the load module, preceded by a BLDL macro instruction 

if you can shorten the search time by using it. The control program returns the address of the 

entry point and the addressing mode in register and the length in doublewords in register 1. 

Load this address into register 15. The linkage requirements are the same when passing control 

between load modules as when passing control between control sections in the same load 

module: register 13 must contain a save area address, register 14 must contain the return 

address, and register 1 is used to pass parameters in a parameter list. A branch instruction, a 

branch and link instruction, a branch and save instruction, a branch and save and set mode 

instruction (BASSM), or a CALL macro instruction can be used to pass control, using register 

15. Use BASSM only if there is to be an addressing mode switch. The return will be made 

directly to your program. 

Notes: 

1. You must use a branch and save and set mode instruction if passing control to a module in a 
different addressing mode. 

2. When control is passed to a load module without using the control program, you must check 
the load module attributes and current status of the copy yourself, and you must check the 
status in all succeeding uses of that load module during the job step, even when the control 
program is used to pass control. 

The reason you have to keep track of the usability of the load module has been discussed j 

previously; you are not allowing the control program to determine whether you can use a \ 

particular copy of the load module. The following paragraphs discuss your responsibilities 

when using load modules with various attributes. You must always know what the reusability 

attribute of the load module is. If you do not know, you should not attempt to pass control 

yourself. 

If the load module is reenterable, one copy of the load module is all that is ever required for a 
job step. You do not have to determine the status of the copy; it can always be used. You can 
pass control by using a CALL macro instruction, a branch, a branch and link instruction, a 
branch and save instruction, or a branch and save and set mode instruction (BASSM). Use 
BASSM only if there is to be an addressing mode switch. 

If the load module is serially reusable, one use of the copy must be completed before the next 
use begins. If your job step consists of only one task, preventing simultaneous use of the same 
copy involves making sure that the logic of your program does not require a second use of the 
same load module before completion of the first use. An exit routine must not require the use 
of a serially reusable load module also required in the main program. 

Preventing simultaneous use of the same copy when you have more than one task in the job 

step requires more effort on your part. You must still be sure that the logic of the program for 

each task does not require a second use of the same load module before completion of the first 

use. You must also be sure that no more than one task requires the use of the same copy of the 

load module at one time; the ENQ macro instruction can be used for this purpose. Properly 

used, the ENQ macro instruction prevents the use of a serially reusable resource, in this case a 

load module, by more than one task at a time. Refer to "Resource Control" for a complete . 

discussion of the ENQ macro instruction. A conditional ENQ macro instruction can also be ■ 

used to check for simultaneous use of a serially reusable resource within one task. 

36 Supervisor Services and Macro Instructions 



> 



1 



If the load module is nonreusable, each copy can only be used once; you must be sure that you 
use a new copy each time you require the load module. You can ensure that you always get a 
new copy by using a LINK macro instruction or by doing as follows: 

1 . Issue a LOAD macro instruction before you pass control. 

2. Pass control using a branch, branch and link, branch and save, branch and save and set 
mode instruction, or a CALL macro instruction. 

3. Issue a DELETE macro instruction as soon as you are through with the copy. 

How Control is Returned 

The return of control between load modules is the same as return of control between two 
control sections in the same load module. The program in the load module returning control is 
responsible for restoring registers 2-14, possibly loading a return code in register 15, passing 
control using the address in register 14 and possibly setting the correct addressing mode. The 
program in the load module to which control is returned can expect registers 2-13 to be 
unchanged, register 14 to contain the return address, and optionally, register 15 to contain a 
return code. Control can be returned using a branch instruction, a branch and set mode 
instruction or the RETURN macro instruction. If control was passed without using the control 
program, control returns directly to the calling program. However, if control was originally 
passed using the control program, control returns first to the control program, then to the 
calling program. 

The action taken by the control program is as follows. The control program returns in the 
caller's addressing mode. When control was passed using a LINK or ATTACH macro 
instruction, the responsibility count was increased by one for the copy of the load module to 
which control was passed to ensure that the copy would be in virtual storage as long as it was 
required. The return of control indicates to the control program that this use of the copy is 
completed, and so the responsibility count is decreased by one. The virtual storage area 
containing the copy is made available when the responsibility count reaches zero. 

Passing Control without Return 

The XCTL macro instruction is used to pass control between load modules when no return of 
control is required. You can also pass control using a branch instruction; however, when you 
pass control in this manner, you must protect against multiple uses of nonreusable or serially 
reusable modules. The following paragraphs discuss the requirements for passing control 
without return in each case. 

Passing Control Using a Branch Instruction 

The same requirements and procedures for protecting against reuse of a nonreusable copy of a 
load module apply when passing control without return as were stated under "Passing Control 
With Return." The procedures for passing control are as follows. 

A LOAD macro instruction should be issued to obtain a copy of the load module. The entry 
address and addressing mode returned in register are loaded into register 15. The linkage 
requirements are the same when passing control between load modules as when passing control 
between control sections in the same load module; register 13 must be reloaded with the old 
save area address, then registers 14 and 2-12 restored from that old save area. Register 1 is 
used to pass parameters in a parameter list. If the addressing mode does not change, a branch 
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instruction is issued to pass control to the address in register 15; if the addressing mode does 
change, a branch and save and set mode macro instruction is used. 

Note: Mixing branch instructions and XCTL macro instructions is hazardous. The next topic 
explains why. 



Using the XCTL Macro Instruction 



The XCTL macro instruction, in addition to being used to pass control, is used to indicate to 
the control program that this use of the load module containing the XCTL macro instruction is 
completed. Because control is not to be returned, the address of the old save area must be 
reloaded into register 13. The return address must be loaded into register 14 from the old save 
area, as must the contents of registers 2-12. The XCTL macro instruction can be written to 
request the loading of registers 2-12, or you can do it yourself. If you restore all registers 
yourself, do not use the EP parameter. This creates an inline parameter list that can only be 
addressed using your base register, and your base register is no longer valid. If EP is used, you 
must have XCTL restore the base register for you. 

When using the XCTL macro instruction, you pass parameters in a parameter list. In this case, 
however, the parameter list (or the parameter data) must be established in a portion of virtual 
storage outside the current load module containing the XCTL macro instruction. This is 
because the copy of the current load module may be deleted before the called load module can 
use the parameters, as explained in more detail below. 

The XCTL macro instruction is similar to the LINK macro instruction in the method used to 
pass control: control is passed by way of the control program using a control program 
parameter list. The control program loads a copy of the load module, if necessary, loads the 
entry address in register 15, saves the address passed in register 14, and passes control to the 
address in register 15. The control program adds one to the responsibility count for the copy of 
the load module to which control is to be passed and subtracts one from the responsibility 
count for the current load module. The current load module in this case is the load module last 
given control using the control program in the performance of the active task. If you have been 
passing control between load modules without using the control program, chances are the 
responsibility count will be lowered for the wrong load module copy. And remember, when the 
responsibility count of a copy reaches zero, that copy may be deleted, causing unpredictable 
results if you try to return control to it. 

Figure 26 shows how this could happen. Control is given to load module A, which passes 
control to the load module B (step 1) using a LOAD macro instruction and a branch and link 
instruction. Register 14 at this time contains the address of the instruction following the branch 
and link. Load module B then is executed, independently of how control was passed, and issues 
an XCTL macro instruction when it is finished (step 2) to pass control to load module C. The 
control program knowing only of load module A, lowers the responsibility count of A by one, 
resulting in its deletion. Load module C is executed and returns to the address which used to 
follow the branch and link instruction. Step 3 of Figure 26 indicates the result. 

Two methods are available for ensuring that the proper responsibility count is lowered. One 
way is to always use the control program to pass control with or without return. The other 
method is to use only LOAD and DELETE macro instructions to determine whether or not a 
copy of a load module should remain in virtual storage. 
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Figure 26. Misusing Control Program Facilities Causes Unpredictable Results 
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Additional Entry Points 



Through the use of linkage editor facilities you can specify as many as 17 different names (a 
member name and 16 aliases) and associated entry points within a load module. It is only 
through the use of the member name or the aliases that a copy of the load module can be 
brought into virtual storage. Once a copy has been brought into virtual storage, however, 
additional entry points can be provided for the load module, subject to one restriction. The 
load module copy to which the entry point is to be added must be one of the following: 

• A copy that satisfied the requirements of a LOAD macro instruction issued during the same 
task 

• The copy of the load module most recently given control through the control program in 
performance of the same task 

The entry point is added through the use of the IDENTIFY macro instruction, which can be 
issued only by a program running under a program request block (PRB). The IDENTIFY 
macro instruction cannot be issued by supervisor call routines or asynchronous exit routines 
established using other supervisor macro instructions. 

When you use the IDENTIFY macro instruction, you specify the name to be used to identify 

the entry point, and the virtual storage address of the entry point in the copy of the load 

module. The address must be within a copy of a load module that meets the requirements 

listed above; if it is not, the entry point will not be added, and you will be given a return code 

of OC (hexadecimal). The name can be any valid symbol of up to eight characters, and does 

not have to correspond to a name or symbol within the load module. The name must not be - 

the same as any other name used to identify any load module available to the control program; tt 

duplicate names cause errors. The control program checks the names of all load modules in the 

link pack area, and the job pack area when you issue an IDENTIFY macro instruction, and 

provides a return code of 8 if a duplicate is found. You are responsible for not duplicating a 

member name or an alias in any of the libraries. 

IDENTIFY services sets the addressing mode of the alias entry point equal to the addressing 
mode of the major entry point. 

If an authorized caller creates an alias for a module in the pageable link pack area, IDENTIFY 
services places an entry for the alias on the active link pack area queue. If an unauthorized 
caller creates an alias for a module in the pageable link pack area, IDENTIFY services places 
an entry for the alias on the task's job pack queue. 



Entry Point and Calling Sequence Identifiers as Debugging Aids 

An entry point identifier is a character string of up to 70 characters that can be specified in a 
SAVE macro instruction. The character string is created as part of the SAVE macro 
instruction "expansion. 

A calling sequence identifier is a 16-bit binary number that can be specified in a CALL or a 
LINK macro instruction. When coded in a CALL or a LINK macro instruction, the calling 
sequence identifier is located in the two low-order bytes of the fullword at the return address. 
The high-order two bytes of the fullword form a NOP instruction. 
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Resource Control 



Task Synchronization 



Some planning on your part is required to determine what portions of one task are dependent 
on the completion of portions of all other tasks. The POST macro instruction is used to signal 
completion of an event; the WAIT and EVENTS macro instructions are used to indicate that a 
task cannot proceed until one or more events have occurred. An event control block is used 
with the WAIT, EVENTS or POST macro instructions; it is a fullword on a fullword boundary, 
as shown in Figure 27. 

An event control block is also used when the ECB parameter is coded in an ATTACH macro 
instruction. In this case the control program issues the POST macro instruction for the event 
(subtask termination). Either the 24-bit (bits 8 to 31) return code in register 15 (if the task 
completed normally) or the completion code specified in the ABEND macro instruction (if the 
task was abnormally terminated) is placed in the event control block as shown in Figure 27. 
The originating task can issue a WAIT or EVENTS WAIT = YES macro instruction specifying 
the event control block; the task will not regain control until after the event has taken place and 
the event control block is posted (except if an asynchronous event occurs, for example, timer 
expiration). 

12 31 



W 



completion code 



Figure 27. Event Control Block 

When an event control block is originally created, bits (wait bit) and 1 (post bit) must be set 
to zero. If an ECB is reused, bits and 1 must be set to zero before a WAIT, EVENTS ECB = 
or POST macro instruction can be specified. If, however, the bits are set to zero before the 
ECB has been posted, any task waiting for that ECB to be posted will remain in the wait state. 
When a WAIT macro instruction is issued, bit of the associated event control block is set to 
1. When a POST macro instruction is issued, bit 1 of the associated event control block is set 
to 1 and bit is set to 0. For an EVENTS type ECB, POST also puts the completed ECB 
address in the EVENTS table. 

A WAIT macro instruction can specify more than one event by specifying more than one event 
control block. (Only one WAIT macro instruction can refer to a event control block at a time, 
however.) If more than one event control block is specified in a WAIT macro instruction, the 
WAIT macro instruction can also specify that all or only some of the events must occur before 
the task is taken out of the wait condition. When a sufficient number of events have taken 
place (event control blocks have been posted) to satisfy the number of events indicated in the 
WAIT macro instruction, the task is taken out of the wait condition. 
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An optional parameter, LONG = YES or NO, allows you to indicate whether the task is 
entering a long wait or a regular wait. A long wait should never be considered for I/O activity. 
However, you might want to use a long wait when waiting for an operator response to a 
WTOR macro instruction. 



Using a Serially Reusable Resource 
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When one or more programs using a serially reusable resource modify the resource, they must 
not use the resource simultaneously with other programs. Consider a data area in virtual 
storage that is being used by programs associated with several tasks of a job step. Some of the 
programs are only reading records in the data area; because they are not updating the records, 
they can access the data area simultaneously. Other programs using the data area, however, are 
reading, updating, and replacing records in the data area. Each of these programs must serially 
acquire, update, and replace records by locking out other programs. In addition, none of the 
programs that are only reading the records want to use a record that another program is 
updating until after the record has been replaced. 

If your program uses a serially reusable resource, you must prevent incorrect use of the 
resource. You must ensure that the logic of your program does not require the second use of 
the resource before completion of the first use. Be especially careful when using a serially 
reusable resource in an exit routine; because exit routines get control asynchronously with 
respect to your program logic, the exit routine could obtain a resource already in use by the 
main program. When more than one task is involved, using the ENQ macro instruction 
correctly can prevent simultaneous use of a serially reusable resource. 

The ENQ macro instruction requests that the control program assign control of a resource to 
the active task. The control program determines the status of the resource, and does one of the 
following: 

• If the resource is available, the control program grants the request by returning control to 
the active task. 

• If the resource has been assigned to another task, the control program delays assignment of 
control by placing the active task in a wait condition until the resource becomes available. 

• Passes back a return code indicating the status of the resource. 

• Abends the caller on unconditional requests that would otherwise result in a non-zero 
return code. 

When the status of the resource changes so that the waiting task can get control, the task is 
taken out of the wait condition and placed in the ready condition. 

The DEQ macro instruction is used in conjunction with the ENQ macro instruction. If used 
properly, ENQ/DEQ can protect serially reusable resources. The rules for proper use of 
ENQ/DEQ are as follows: 

• Everyone must use ENQ/DEQ. 

• Everyone must use the same names and scope values for the same resources. 

• Everyone must use consistent ENQ/DEQ protocol. d 

V 
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Naming the Resource 

Represent the resource in the ENQ macro instruction by two names known as the qname and 
the rname, and by a scope indicator. The qname and rname need not have any relation to the 
actual name of the resource. The control program does not associate the name with the actual 
resource; it merely processes requests having the same qname, rname, and scope on a first-in, 
first-out basis. It is up to you to associate the names with the actual resource by ensuring that 
all users of the resource use qname, rname, and scope to represent the same resource. The 
control program treats requests having different qname, rname, and scope combinations as 
requests for different resources. Because the control program cannot determine the real name 
of the resource from the qname, rname, and scope, a task could use the resource by specifying a 
different qname, rname, and scope combination or by accessing the resource without using 
ENQ. In this case, the control program cannot provide any protection. 

You will be abnormally terminated if you use SYSZ as the first four characters of a qname 
(unless you are authorized, in key 0, or in supervisor state) because the control program uses 
SYSZ for its qnames. Avoid using SYSA through SYSY because the control program 
sometimes uses these characters for its qnames as well. Either check with your system 
programmer to see which of the SYSA through SYSY combinations you can use or avoid using 
SYSx (where x is alphabetic) to begin qnames. 

You can request a scope of STEP, SYSTEM, or SYSTEMS. 

Use a scope of STEP if the resource is used only in your address space. The control program 
uses the address space identifier to make your resource unique in case someone else in another 
address space uses the same qname and rname and a scope of STEP. 

Use a scope of SYSTEM if the resource is available to more than one address space in the 
system. All programs that serialize on the resource must use the same qname and rname and a 
scope of SYSTEM. For example, to prevent two jobs from using a named resource 
simultaneously, use SYSTEM. 

Use a scope of SYSTEMS if the resource is available to more than one system. All programs 
that serialize on the resource must use the same qname and rname and a scope of SYSTEMS. 
For example, to prevent two processors from using a named resource simultaneously, use 
SYSTEMS. Note that the control program considers a resource with a SYSTEMS scope to be 
different from a resource represented by the same qname and rnaime but with a scope of STEP 
or SYSTEM. 

Types of Resources that Can Be Shared 

Global resource serialization, which handles ENQs, DEQs, and RESERVES, recognizes two 
types of resources. These are local resources and global resources. 

A local resource is a resource identified on the ENQ or DEQ macro instruction by a scope of 
STEP or SYSTEM. (Note that a resource with a scope of SYSTEM has its scope converted to 
SYSTEMS if the resource appears in the SYSTEM inclusion resource name list. See Planning: 
Global Resource Serialization for information about resource name lists.) A local resource is 
recognized and serialized only within the requesting operating system. The local resource 
queues are updated to reflect each request for a local resource. If a system is not operating 
under global resource serialization (that is, the system is not part of a global resource 
serialization complex), all resources requested are treated as local resources, and a resource 
requested by a RESERVE macro instruction always causes a hardware reserve for the entire 
volume. 
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If a system is part of a global resource serialization complex, a global resource is identified on 
the ENQ or DEQ macro instruction by a scope of SYSTEMS. (Note that a resource with a 
scope of SYSTEMS has its scope changed to SYSTEM if the resource appears in the 
SYSTEMS exclusion resource name list.) A global resource is recognized and serialized by all 
systems in the global resource serialization complex. 

Requesting Exclusive or Shared Control 

To request exclusive control of the resource, code E in the ENQ macro instruction. If you are 
changing the resource, you must request exclusive control. 

To request shared control of the resource, code S in the ENQ macro instruction. Request 
shared control only if you are not changing the resource. 

Limiting Concurrent Requests for Resources 

In order to prevent any one job, started task, or TSO user from generating too many 
concurrent requests for resources, global resource serialization counts and limits the number of 
ENQs in each address space. When a user issues an ENQ, global resource serialization 
increases the count of outstanding requests for that address space by one and decreases the 
count by one when the user issues a DEQ. 

When the computed count reaches the threshold value or limit, global resource serialization 
processes subsequent requests as follows: 

• Unconditional requests (ENQs that use the RET = NONE option) are abended with a 
system code of X'538'. 

• Conditional requests (ENQs that specify the RET = HAVE or RET = USE option) are 
rejected and the user receives a return code of X'18'. 

The RESERVE and GQSCAN macros, which also increase the count of outstanding requests, 
are described in SPL: System Macros and Facilities. 

Processing the Request 

The control program constructs a unique list for each qname, rname, and scope combination it 
receives in an ENQ or RESERVE macro instruction. When a task makes a request by issuing 
an ENQ or RESERVE macro instruction, the control program searches the existing lists for a 
matching qname, rname, and scope. If it finds a match, the control program adds the task's 
request to the end of the existing list; the list is not ordered by the priority of the tasks on it. If 
the control program does not find a match, it creates a new list, and adds the task's request as 
the first (and only) element. The task gets control of the resource based on the following: 

• The position of the task's request on the list 

• Whether or not the request was for exclusive or shared control 

Figure 28 shows the status of a list built for a qname, rname, and scope combination. The S 

or E next to the entry indicates that the request was for either shared or exclusive control. The 

task represented by the first entry on the li§t always gets control of the resource, so the task 

represented by ENTRY1 (Figure 28, Step 1) is assigned the resource. The request that ■ 
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established ENTRY2 was for exclusive control, so the corresponding task is placed in the wait 
condition, along with the tasks represented by all the other entries in the list. 



ENTRYl (S) 




ENTRY2 (E) 




ENTRY3 (S) 


ENTRY2 (E) 


ENTRY3 (S) 


ENTRY3 (S) 


ENTRY4 (S) 


ENTRY4 (S) 


ENTRY4 (S) 


ENTRY5 (E) 


ENTRY5 (E) 


ENTRY5 (E) 


ENTRY6 (S) 
Stepl 


ENTRY6 (S) 
Step 2 


ENTRY6 (S) 
Step 3 



Figure 28. ENQ Macro Instruction Processing 

Eventually, the task represented by ENTRYl releases control of the resource, and the ENTRYl 
is removed from the list. As shown in Figure 28, Step 2, ENTRY2 is now first on the list, and 
the corresponding task is assigned control of the resource. Because the request that established 
ENTRY2 was for exclusive control, the tasks represented by all the other entries in the list 
remain in the wait condition. 

Figure 28, Step 3, shows the status of the list after the task represented by ENTRY2 releases 
the resource. Because ENTRY3 is now at the top of the list, the task represented by ENTRY3 
gets control of the resource. ENTRY3 indicates that the resource can be shared, and, because 
ENTRY4 also indicates that the resource can be shared, ENTRY4 also gets control of the 
resource. In this case, the task represented by ENTRY5 does not get control of the resource 
until the tasks represented by ENTRY3 and ENTRY4 release control because ENTRY5 
indicates exclusive use. 

The control program uses the following general rules in manipulating the lists: 

• The task represented by the first entry in the list always gets control of the resource. 

• If the request is for exclusive control, the task is not given control of the resource until its 
request is the first entry in the list. 



• If the request is for shared control, the task is given control either when its request is first 
in the list or when all the entries before it in the list also indicate a shared request. 

• If the request is for several resources, the task is given control when all of the entries 
requesting exclusive control are first in their respective lists and all the entries requesting 
shared control are either first in their respective lists or are preceded only by entries 
requesting shared control. 



Duplicate Requests for a Resource 
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A duplicate request occurs when a task issues an ENQ macro instruction to request a resource 
that the task already controls. For example, if a task that has control of a resource issues an 
unconditional ENQ macro to request the same resource, the task is abnormally terminated. If 
you make a duplicate request for a resource you might be abnormally terminated. With the 
second request, the control program recognizes the contradiction and returns control to the task 
with a non-zero return code or abnormally terminates the task. You should design your 
program to ensure that a second request for a resource made by the same task is never issued 
until control of the resource is released for the first use. Be especially careful when 
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using an ENQ macro instruction in an exit routine. Two specific reasons why the use of ENQ 
in an exit routine must be carefully planned are: 

• The exit may be entered more than once for the same TCB. 

• An exit routine may request resources already obtained by some other process associated 
with the TCB. 

More information on this topic follows under "Conditional and Unconditional Requests." 

Releasing the Resource 

Use the DEQ macro instruction to release a serially reusable resource that you obtained by 
using an ENQ macro instruction. If you try to release a resource for which you do not have 
control, you either get a non-zero return code or you are abnormally terminated. It is possible 
for many tasks to be placed in the wait condition while one task is assigned control of the 
resource. Having many tasks in the wait state might reduce the amount of work being done by 
the system, therefore, you should issue a DEQ macro instruction as soon as possible to release 
the resource, so that other tasks can use it. If a task terminates without releasing a resource, 
the control program releases the resource automatically. 

Conditional and Unconditional Requests 

Up to this point, only unconditional requests have been considered. You can, however, use the 
ENQ and DEQ macro instructions to make conditional requests by using the RET parameter. 
For authorized programs, the ECB parameter is another way to make conditional requests with 
the ENQ macro instruction. This parameter, restricted to APF-authorized (key or supervisor 
state) programs, is described in S PL: System Macros and Facilities, Volume 2. One reason for 
making a conditional request is to avoid the abnormal termination that occurs if you issue two 
ENQ macro instructions for the same resource within the same task or when a DEQ macro 
instruction is issued for a resource for which you do not have control. 

The RET = parameter of ENQ and DEQ can provide the following options: 

RET = CHNG indicates the status of the resource specified is changed from shared to exclusive control. 

RET = HAVE indicates that control of the resource is requested conditionally; that is, control is requested only if a 
request has not been made previously for the same task. 

RET = TEST indicates the availability of the resource is to be tested, but control of the resource is not requested. 

RET = USE indicates control of the resource is to be assigned to the active task only if the resource is immediately 
available. If any of the resources are not available, the active task is not placed in a wait condition. 

For the following descriptions, the term "active task" mean the task issuing the ENQ macro 
instruction. No reference is intended to different tasks which might be active in other 
processors of a multiprocessor. 
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RET = TEST is used by a task to test the status of the corresponding qname, rname, and scope 
combination, without changing the list in any way or waiting for the resource. 

• A return code of indicates that the active task does not now have control of the resource, 
but could have been given immediate control if it had been requested, because no other task 
has control of the resource. 

• A return code of 4 indicates that another task has control of the resource, and the active 
task would have been placed in a wait condition if it had made an unconditional request. 

• A return code of 8 indicates that the active task already has control of the resource. 

• A return code of 14 indicates that the active task does not yet have control of the resource, 
but is in the list to be given control at a later time when other task(s) release the resource. 

Note: For return code 14 to occur, the restricted use of the ECB = parameter of the ENQ 
must have been used to make an entry on the list without placing the task in a wait 
condition. 

RET = TEST is most useful for determining if the task already has control of the resource. It is 
less useful for determining the status of the list and taking action based on that status. In the 
interval between the time the control program checks the status and the time your program 
checks the return code and issues another ENQ macro instruction, another task could have 
been made active, and the status of the list could have changed. 

RET = USE is used if you want your task to assigned control of the resource only if the 
resource is immediately available. If the resource is not immediately available, no entry will be 
made on the list and the task will not be made to wait. RET = USE is most useful when there 
is other processing that can be done without using the resource. For example, by issuing a 
preliminary ENQ with RET = USE in an interactive task, you can attempt to gain control of a 
needed resource without locking your terminal session. If the resource is not available, you can 
do other work rather than enter a long wait for the resource. 

• A return code of indicates that the active task did not have control of the resource prior 
to issuing the ENQ, but now has been given control and the corresponding entry has been 
put in the list. 

• A return code of 4 indicates that the active task has not been given control of the resource, 
and an entry has not been made in the list, because another task already has control of the 
resource. 

• A return code of 8 indicates that the active task already has control of the resource. 

• A return code of 14 indicates that the active task does not yet have control of the resource, 
but is in the list to be given control at a later time when other task(s) release the resource. 

• A return code of 18 indicates that the limit for the number of concurrent resource requests 
has been reached. The task does not have control of the resource unless some previous 
ENQ/RESERVE request caused the task to obtain control of the resource. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key or 
supervisor state) programs, is described in SPL: System Macros and Facilities, Volume 2. 
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RET = CHNG is used to change a previous request from shared to exclusive control. 

• A return code of indicates that the active task now has exclusive control of the resource. 
Either exclusive control was already held, or shared control was converted to exclusive 
control as requested. 

• A return code of 4 indicates that the requested change in attribute cannot be honored, 
because the active task is currently sharing the resource with another task. 

• A return code of 8 indicates that the active task does not have an entry on the list for the 
specified resource. There is nothing to change. 

• A return code of 14 indicates that the active task does have an entry on the list for the 
resource, but is not yet in control of the resource. No change is made. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key or 
supervisor state) programs, is described in SPL: System Macros and Facilities, Volume 2. 

RET = HAVE is used with both the ENQ and DEQ macro instructions to specify a conditional 
request for control of a resource (ENQ) when you do not know whether or not you have 
already requested control of that resource. RET = HAVE is used to release control (DEQ), 
with protection against abnormal termination of the active task, if an ENQ is duplicated or a 
DEQ is issued for a resource not held. If the resource is owned by another task, you will be 
put in a wait condition until the resource becomes available. 

RET = HAVE with ENQ can make the active task wait until the resource becomes available. 

• A return code of indicates that the active task did not previously have an entry on the list 
or control of the resource, but has now been given control. 

• A return code of 8 indicates that the active task already has control of the resource and 
already has an entry on the list. (Without RET = HAVE, this situation would cause 
abnormal termination. With RET = HAVE, it is effectively a no-operation.) 

• A return code of 14 indicates that the active task has entry on the list for the resource, but 
is not yet in control of the resource. No change is made. 

For authorized programs, the ECB parameter is another way to make conditional requests 
with the ENQ macro instruction. This parameter, restricted to APF-authorized (key or 
supervisor state) programs, is described in SPL: System Macros and Facilities, Volume 2. 

For DEQ: 

• A return code of indicates that the DEQ routine found an entry for the active task on the 
list for the specified resource, and has removed the entry. If the active task held control of 
the resource, this action relinquishes control. If the active task did not hold control of the 
resource (because the restricted ECB parameter had been used with ENQ, and control has 
not meanwhile become available), the DEQ routine simply removes the entry from the list 
without affecting control of the resource. 

• A return code of 4 indicates the resource has been requested for the task, but the task has 
not been assigned control. The task is not removed from the wait condition. (This return 
code could result if DEQ is issued within an exit routine which was given control because 
of an interruption). 
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• A return code of 8 indicates that the active task did not have an entry on the list for the 
specified resource. There was no entry to dequeue. 

If ENQ and DEQ are used in an asynchronous exit routine, code RET = HAVE to avoid 
possible abnormal termination. 



Avoiding Interlock 



An interlock condition happens when two tasks are waiting for each others' completion, but 
neither task can get the resource it needs to complete. Figure 29 shows an example of an 
interlock. Task A has exclusive access to resource M, and higher-priority task B has exclusive 
access to resource N. When task B requests exclusive access to resource M, B is placed in a 
wait state because task A has exclusive control of resource M. 

The interlock becomes complete when task A requests exclusive control of resource N. The 
same interlock would have occurred if task B issued a single request for multiple resources M 
and N prior to task A's second request. The interlock would not have occurred if both tasks 
had issued single requests for multiple resources. Other tasks requiring either of the resources 
are also in a wait condition because of the interlock, although in this case they did not 
contribute to the conditions that caused the interlock. 



Task A Task B 

ENQ (M,A,E, 8, SYSTEM) 

ENQ (N,B,E, 8, SYSTEM) 
ENQ (M, A, E, 8, SYSTEM) 

ENQ (N,B,E, 8, SYSTEM) 



Figure 29. Interlock Condition 

The above example involving two tasks and two resources is a simple example of an interlock. 
The example could be expanded to cover many tasks and many resources. It is imperative that 
you avoid interlock. The following procedures indicate some ways of preventing interlocks. 

• Do not request resources that you do not need immediately. If you can use the serially 
reusable resources one at a time, request them one at a time and release one before 
requesting the next. 

• Share resources as much as possible. If the requests in the lists shown in Figure 29 had 
been shared, there would have been no interlock. This does not mean you should share a 
resource that you will modify. It does mean that you should analyze your requirements for 
the resources carefully, and not request exclusive control when shared control is enough. 

• Use the ENQ macro instruction to request control of more than one resource at a time. 
The requesting program is placed in a wait condition until all of the requested resources are 
available. Those resources not being used by any other program immediately become 
exclusively available to the waiting program. For example, instead of coding the two ENQ 
macro instructions shown in Figure 30, you could code the one ENQ macro instruction 
shown in Figure 31. If all requests were made in this manner, the interlock shown in 
Figure 29 could not occur. All of the requests from one task would be processed before 
any of the requests from the second task. The DEQ macro instruction can release a 
resource as soon as it is no longer needed; resources requested in a multiple ENQ can be 
individually released through separate DEQ instructions. 
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ENQ (NAME1ADD,NAME2ADD,E, 8, SYSTEM) 
ENQ ( NAME 3 ADD , NAME 4 ADD , E , 10 , SYSTEM) 



Figure 30. Two Requests For Two Resources 



ENQ (NAME1ADD,NAME2ADD,E, 8, SYSTEM, NAME3ADD,NAME'4ADD,E, 10, SYSTEM) 



Figure 31. One Request For Two Resources 

• If the use of one resource always depends on the use of a second resource, then you can 
define the pair of resources as one resource in the ENQ and DEQ macro instructions. You 
can use this procedure for any number of resources that are always used in combination. 
However, the control program cannot protect these resources if they are also requested 
independently. Any requests must always be for the set of resources. 

• If there are many users of a group of resources and some of the users require control of a 
second resource while retaining control of the first resource, it is still possible to avoid 
interlocks. In this case, each user should request control of the resources in the same order. 
For instance, if resources A, B, and C are required by many tasks, the requests should 
always be made in the order of A, B, and C. An interlock situation will not develop, since 
requests for resource A will always precede requests for resource B. 
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Resource Access Control Facility (RACF) 



The Resource Access Control Facility (RACF) provides software access control measures that 
can be used to enhance data security in a computing system. RACF can be used in addition to 
any present data security measures currently being used. 

RACF provides the ability to specify access authorities under which the resources (for example, 
DASD data sets, tape volumes, and DASD volumes) in the system are made available to the 
users of the system. 

When users, groups, and resources are defined to RACF, RACF builds and stores their 
descriptions in profiles on the RACF data set. The profiles will be used by RACF for 
RACHECK authorization checking. 

For more information on RACF, see Resource Access Control Facility (RACF): General 
Information Manual. 



RACHECK Macro Instruction 



RACHECK processing determines if a user is authorized to obtain use of a resource protected 

by RACF. When a user requests access to a RACF-protected resource, acceptance of the 

request is based upon the identity of the user and whether the user has been permitted sufficient 

access authority to the resource. £ 
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RACF performs system authorization checking when a resource manager that controls a 
RACF-protected resource issues the RACHECK macro instruction before allowing a user 
access to the resource. 



RACSTAT Macro Instruction 



RACSTAT processing determines if RACF is active and optionally determines if RACF 
protection is in effect for a given resource class. The macro can be used to determine if a 
resource class is defined to RACF. 



FRACHECK Macro Instruction 



FRACHECK processing determines if a user is authorized to obtain a RACF-protected 
resource. FRACHECK is a branch-entered service that performs authorization checking for 
RACF-protected resources whose profiles have been brought into main storage by the 
RACLIST routine. 



System Authorization Facility (SAF) 
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The System Authorization Facility (SAF) provides a system interface that conditionally directs 
control to the Resource Access Control Facility (RACF), if RACF is present, and/or a 
user-supplied processing routine when receiving a request from a resource manager. SAF does 
not require any other program product as a prerequisite, but overall system security functions 
are greatly enhanced and complemented by the concurrent use of RACF. The key element in 
SAF is the MVS router. 



MVS Router 



SAF provides an installation with centralized control over system security processing by using a 
system service called the MVS router. The MVS router provides a focal point and a common 
system interface for all products providing resource control. The resource managing 
components and subsystems call the router as part of certain decision-making functions in their 
processing, such as access control checking and authorization-related checking. These functions 
are called "control points." This single SAF interface encourages the use of common control 
functions shared across products and across systems. 

The router is always present whether or not RACF is present. If RACF is available in the 
system, the router passes control to the RACF routine (ICHRFROO) that invokes the 
appropriate RACF function based on the parameter information and the RACF router table 
(ICHRFR01), which associates router invocations with RACF functions. The RACF router 
table is described in the SPL: Resource Access Control Facility (RACF). Before it calls the 
RACF routine, the router calls an optional, user-supplied security processing exit if one has 
been installed. The MVS router exit is described in SPL: Supervisor. 

Control points that issue the RACROUTE macro instruction enter the MVS router in the same 
key and state as the RACROUTE issuer. Control points that continue to issue the RACF 
macro instructions go directly to RACF, bypassing the router. 
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MVS Router Parameter List 



The MVS router parameter list (mapped by macro ICHSAFP) is generated when the 
RACROUTE macro is issued and describes the security processing request by providing the 
request type. If the router installation exit exists, the router passes the parameter list to this 
exit. If RACF is active, the router uses the request type information to invoke the appropriate 
RACF function. 



Field Name 


Offset 


Length 


SAFPRRET 


0(0) 


,4 


SAFPRREA 


4(4) 


4 


SAFPPLN 


8(8) 


2 




10(A) 


2 


SAFPREQT 


12(C) 


2 





14(E) 


2 


SAFPREQR 


16 (10) 


4 


SAFPSUBS 


20 (14) 


4 


SAFPWA 


24 (18) 


4 




28 (1C) 


4 




32 (20) 


4 


SAFPRACP 


36 (24) 


4 



Description 

Return code - Defines the RACF or installation exit return code. 

Reason code - Defines the RACF or installation exit reason code. 

Length - Defines the length of the SAFP parameter list. 

Reserved 

Request type - A binary halfword corresponding to the request type on the 
RACROUTE macro. The request type and the associate request numbers 
are listed below. 

AUTH (RACHECK) - 1 (01) 
FASTAUTH (FRACHECK) - 2 (02) 

Reserved 

Request name address - Points to an 8-byte character field containing the 
control point name. 

Subsystem name address - Points to an 8-byte character field containing 
the calling subsystem's name, version, and release level. 

SAF work area address - Points to a 512-byte work area for use by the 
MVS router and the RACF front end routine. 

Reserved 

Reserved 

Offset - Contains the (signed) offset from the start of the MVS router 
parameter list to the RACF parameter list. 
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RACROUTE Macro Instruction 



The RACROUTE macro instruction is the interface to the MVS router that provides a focal 
point and a common system interface for all products providing resource control. The MVS 
router first invokes an optional installation exit and then invokes RACF, if RACF is active and 
installed on the system. 

The RACROUTE macro accepts all valid parameters for the RACF macros (RACHECK and 
FRACHECK) and internally issues the appropriate RACF macro to generate a RACF 
parameter list. When the RACROUTE macro internally invokes the RACF macros, 
RACROUTE verifies that only valid parameters have been coded and then passes the 
parameters to the MVS router. Existing control points that invoke RACF processing via the 
supervisor call interface can continue to do so or can replace the RACF supervisor calls with 
the RACROUTE macro. 

See the RACROUTE macro in Part II for a description of the return codes. 
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Program Interruption, Recovery /Termination, and Dumping Services 

The supervisor offers many services to detect and process abnormal conditions during system 
execution. The hardware detects certain types of abnormal conditions (such as an attempt to 
execute an instruction with an invalid operation code) and causes program interruptions to 
occur. The software detects other abnormal conditions (such as an attempt to open a data set 
that is not defined to the system, which causes the OPEN routine to request abnormal 
termination by issuing an ABEND macro instruction). 

You can write exit routines to handle specific types of interruptions and abnormal conditions. 
The supervisor initiates the recovery /termination process for your program either when you 
request it (for example, by issuing an ABEND macro instruction) or when MVS/XA detects a 
condition that will degrade the system or destroy data. 



Interruption Services 

Some conditions encountered in a program cause a program interruption. These conditions 
include incorrect parameters and parameter specifications, as well as exceptional results, and are 
known generally as program exceptions. You can disable the interruptions for certain 
exceptions (fixed point and decimal overflow, exponent underflow, and significance) by setting 
the corresponding bits in the program status word (PSW) to zero. 

When a task becomes active for the first time, all program interruptions that can be disabled 
are disabled, and the task uses a standard control program exit routine, included when the 
system was generated. This exit routine gets control when certain program interruptions occur; 
it issues an ABEND macro instruction specifying task abnormal termination and requesting a 
dump. 



Specifying User Exit Routines 
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By issuing the SPIE or ESPIE macro instruction, you can specify your own exit routine to be 
given control for one or more types of program exceptions. If you issue an ESPIE macro 
instruction, you can also pass the address of a parameter list to the exit routine. When one of 
the specified program exceptions occurs in a problem program being executed in the 
performance of a task, the exit routine receives control in the key of the TCB (TCBPKF) and 
in the addressing mode in effect when the SPIE or ESPIE was issued. (If a SPIE macro 
instruction was issued, this is 24-bit addressing mode.) For other program interruptions, part of 
the control program, the recovery termination manager (RTM), gets control. If the SPIE or 
ESPIE macro instruction specifies an exception for which the interruption has been disabled, 
the control program enables the interruption when the macro instruction is issued. 
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The environment established by an ESPIE macro instruction exists for the entire task, until the 
environment is changed by another SPIE/ESPIE macro instruction, or until the program 
creating the ESPIE returns via an SVC 3. Each succeeding SPIE or ESPIE macro instruction 
completely overrides specifications in the previous SPIE or ESPIE macro instruction. You can 
intermix SPIE and ESPIE macro instructions in one program. Only one SPIE or ESPIE 
environment is active at a time. If an exit routine issues a SPIE or ESPIE macro instruction, 
the new SPIE/ESPIE environment does not take effect until the exit routine completes. 

The control program automatically deletes the SPIE/ESPIE exit routine when the RB that 
established the exit terminates. If a caller attempts to delete a specific SPIE/ESPIE 
environment established under a previous RB, the caller is abended with a system completion 
code of X'46D'. A caller can delete all previous SPIE and ESPIE environments (regardless of 
the RB under which they were established) by specifying a token of zero with the RESET 
option of the ESPIE macro instruction or an exit address of zero with the SPIE macro 
instruction. 

Notes: 

1. In MVS/370, the SPIE environment existed for the life of the task. In MVSjXA, the SPIE 
environment is deleted when the request block representing the program that issued the macro 
instruction is deleted. That is, when a program running under MVSjXA completes, any SPIE 
environments created by the program are deleted. This might create an incompatibility with 
MVS 1 370 for programs that depend on the SPIE environment remaining in effect for the life 
of the task rather than the life of the request block. 

2. A SPIE exit routine established while executing in 24-bit addressing mode will not receive 
control if the program executing is in 31-bit addressing mode at the time of the interruption. 

Any problem program, executing in either 24-bit or 31 -bit addressing mode in the performance 
of a task, can issue the ESPIE macro instruction. If your program is executing in 31 -bit 
addressing mode, you cannot issue the SPIE macro instruction. The SPIE macro instruction is 
restricted in use to callers executing in 24-bit addressing mode in the performance of a task. 
The following topics describe how to use the SPIE and ESPIE macro instructions. 

Using the SPIE Macro Instruction 

The PICA and the program interruption element (PIE) contain the information that enables the 
control program to intercept user-specified program interruptions established using the SPIE 
macro instruction. The PIE and its associated PICA are called the "SPIE environment." You 
can modify the contents of the active PICA in order to change the active SPIE environment. 
The PICA and the PIE are described in the following topics. 

Program Interruption Control Area 

The expansion of each standard or list form of the SPIE macro instruction contains a control 
program parameter list called the program interruption control area (PICA). The PICA, as 
shown in Figure 32, contains the new program mask for the interruption types that can be 
disabled in the PSW, the address of the exit routine to be given control when one of the 
specified interruptions occurs, and a code for interruption types (exceptions) specified in the 
SPIE macro instruction. 
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0000 Program 
Mask 


Exit Routine Address 


Interruption Type 



Displacement 
Bytes 



Figure 32. Program Interruption Control Area 

The control program maintains a pointer (in the PIE) to the PICA referred to by the last SPIE 
macro instruction executed. This PICA might have been created by the last SPIE or might 
have been created previously and referred to by the last SPIE. Before returning control to the 
calling program or passing control to another program via an XCTL macro instruction, each 
program that issues a SPIE macro instruction must cause the control program to adjust the 
SPIE environment to the condition that existed previously or to eliminate the SPIE environment 
if one did not exist on entry to the program. When you issue the standard or execute form of 
the SPIE macro instruction, the control program returns the address of the previous PICA in 
register 1. If no SPIE/ESPIE environment existed when the program was entered, the control 
program returns zeroes in register 1 . 






You can cancel the effect of the last SPIE macro instruction by issuing a SPIE macro 
instruction with no parameters. This action does not reestablish the effect of the previous 
SPIE; it does create a new PICA that contains zeroes, thus indicating that you do not want an 
exit routine to process interruptions. You can reestablish any previous SPIE environment, 
regardless of the number or type of subsequent SPIE macro instructions issued, by using the 
execute form of the SPIE specifying the PICA address that the control program returned in 
register 1. The PICA whose address you specify must still be valid (not overlaid). If you 
specify zeroes as the PICA address, the SPIE environment is eliminated. 

Figure 33 shows how to restore a previous PICA. The first SPIE macro instruction designates 
an exit routine called FIXUP that is to be given control if fixed-point overflow occurs. The 
address returned in register 1 is stored in the fullword called HOLD. At the end of the 
program, the execute form of the SPIE macro instruction is used to restore the previous PICA. 
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SPIE FIXUP, (8) Provide exit routine for fixed-point 

overflow 
ST l,HOLD Save address returned in register 1 



L 5, HOLD Reload returned address 

SPIE MF=(E,(5)) Use execute form and old PICA address 



HOLD DC F ' • 



Figure 33. Using the SPIE Macro Instruction 
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Program Interruption Element 



The first time you issue a SPIE macro instruction during the performance of a task, the control 
program creates a 32-byte program interruption element (PIE) in the virtual storage area 
assigned to your job step. Because the PIE is freed the first time you eliminate the SPIE 
environment (by specifying a PICA address of zero in the execute form of the SPIE macro 
instruction or by specifying a SPIE with no parameters), the control program also creates a 
PIE whenever you issue a SPIE macro instruction and no PIE exists. The format of the PIE is 
shown in Figure 34. 
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Figure 34. Program Interruption Element 

The PICA address in the PIE is the address of the program interruption control area used in 
the last execution of the SPIE macro instruction for the task. When control is passed to the 
routine indicated in the PICA, the BC mode old program status word contains the interruption 
code in bits 16-31 (the first byte is the exception extension code and the second is the exception 
code); you can test these bits to determine the cause of the program interruption. The control 
program stores the contents of registers 14,15,0,1, and 2 at the time of the interruption as 
indicated. 
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Using the ESPIE Macro Instruction 



The ESPIE macro instruction extends the functions of the SPIE macro instruction to callers in 
31 -bit addressing mode. The options that you can specify using the ESPIE macro instruction 
are: 



• SET to establish an ESPIE environment (that is, specify the interruptions for which the 
user-exit routine will receive control) 

• RESET to delete the current ESPIE environment and restore the SPIE/ESPIE environment 
specified 

• TEST to determine the active SPIE/ESPIE environment 

If you specify ESPIE SET, you pass the following information to the service routine: 

• A list of the program interruptions to be handled by the exit routine 

• The location of the exit routine 

• The location of a user-defined parameter list 
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The service routine returns a token representing the previously active SPIE or ESPIE 
environment, or zero if there was none. 

If you code ESPIE RESET, you pass the token, which was returned when the ESPIE 
environment was established, back to the ESPIE service routine. The SPIE or ESPIE 
environment corresponding to the token is restored. If you pass a token of zero with RESET, 
all SPIE and ESPIE environments are deleted. 

If you specify ESPIE TEST, you will be able to determine the active SPIE or ESPIE 
environment. An active SPIE environment is represented by a pointer to the PICA, which 
resides in user storage. (The PICA is described earlier in this section.) The active ESPIE 
environment is represented by protected control blocks belonging to the ESPIE service. To 
change an active ESPIE environment, you must issue the ESPIE macro with the SET or 
RESET option. 

There are two control program areas associated with the ESPIE macro instruction. They are 
the extended program interruption element (EPIE) and the fake PICA. The EPIE and the fake 
PICA are described in the following topics. 

The Extended Program Interruption Element (EPIE) 

The control program creates an EPIE the first time you issue an ESPIE macro instruction 
during the performance of a task or whenever you issue an ESPIE macro instruction and no 
EPIE exists. The EPIE is freed when you eliminate the ESPIE environment. 



I 



The EPIE contains the information that the ESPIE service routine passes to the ESPIE exit 
routine when it receives control. When the exit routine receives control, register 1 contains the 
address of the EPIE. (See the topic "Register Contents Upon Entry to User's Exit Routine" for 
the contents of the other registers.) The format of the EPIE is shown in Figure 35. 
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The registers are stored in order-register to register 15. 
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by the two-byte interruption code 
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interruption is a page fault) 
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Figure 35. Extended Program Interruption Element 



The Fake PICA 
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The fake PICA is used by MVS/XA to maintain compatibility between the SPIE and the ESPIE 
macro instructions. If you code a SPIE macro instruction to specify interruptions for which a 
SPIE exit routine is to receive control and if an ESPIE environment was previously active, the 
service routine returns the address of a fake PICA. The fake PICA resides in 24-bit addressable 
storage. The user should not modify its contents. 
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Register Contents Upon Entry to User's Exit Routine 

When control is passed to your routine, the register contents are as follows: 

Register 0: Internal control program information. 

Register 1: Address of the PIE or EPIE for the task that caused the interruption. 

Registers 2-12: Same as when the program interruption occurred. 

Register 13: Address of the save area for the main program. The exit routine cannot use this area. 

Register 14: Return address (to the control program). 

Register 15: Address of the exit routine. The exit routine must be in virtual storage when it is required, and must 

return control to the control program using the address passed in register 14. For an ESPIE macro 
instruction, the control program restores all 16 registers from the EPIE. For a SPIE macro 
instruction, the control program restores registers 14,15,0,1, and 2 from the program interruption 
element after control is returned, but does not restore the contents of registers 3-13. If a program 
interruption occurs when the program interruption exit routine is in control, the control program exit 
routine gets control. 

Functions Performed in User Exit Routines 

Your exit recovery routine must determine the type of interruption that occurred before taking 
corrective action. Determining the type of interruption depends on whether the exit is 
associated with an ESPIE or a SPIE macro instruction. 

• For an ESPIE, your exit recovery routine can check the two-byte interruption code (the 
first byte is the exception extension code and the second is the exception code) at offset 
X'52' in the EPIE. 

• For a SPIE, your exit recovery routine can test bits 16 through 31 (the first byte is the 
exception extension code and the second is the exception code) of the old program status 
word (OPSW in BC mode) in the PIE. 

Note: For both ESPIE and SPIE — If you are using vector instructions and an exception of 8, 
12, 13, 14, or 15 occurs, your recovery routine can check the exception extension code (the first 
byte of the two-byte interruption code in the EPIE or PIE) to determine whether the exception 
was a vector or scalar type of exception. 

Your recovery routine can alter the contents of the registers when control is returned to the 
interrupted program. The procedure for altering the registers also depends on whether the exit 
is associated with an ESPIE or a SPIE. 

• For an ESPIE exit, the recovery routine can alter the contents of registers through 15 in 
the save area in the EPIE because the control program reloads these registers from this area 
when it returns control to the interrupted program. 

• For a SPIE exit, the recovery routine can alter registers 14 through 2 in the register save 
area in the PIE because the control program reloads these registers from this area when it 
returns control to the interrupted program. To change registers 3 through 13, the recovery 
routine must alter the contents of the registers. 

The recovery routine can also alter the last four bytes of the OPSW in the PIE or EPIE. For 
an ESPIE, the recovery routine alters the CC and program mask starting at the third byte in 
the OPSW. By changing the OPSW, the routine can select any return point in the interrupted 
program. In addition, for ESPIE exits, the routine must set the AMODE bit of this four-byte 
address to indicate the addressing mode of the interrupted program. 
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Recovery /Termination Services 
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Part of the control program, the recovery termination manager (RTM), monitors the flow of 
control of software recovery processing and supplies the services of normal and abnormal task 
termination. RTM selects the appropriate recovery or termination process according to the 
status of the system. 

RTM gets control in response to events such as the following: 

• Unanticipated program checks (except those protected by SPIE routines) 

• Machine checks 

• Invalid issuance of an SVC while locked, disabled, in SRB mode, or in cross memory 
mode 1 , or while an enabled, unlocked task mode FRR was established 

• I/O error on page-in request 

• Request by an authorized caller to terminate a task 

• ABEND macro instructions 

RTM invokes any recovery routine that has been established to recover or clean up for the 
process in control. The recovery routine could be one of yours or it could be a system routine. 
If this recovery routine cannot recover from the incident (it requests termination or itself fails), 
RTM invokes the previously-established recovery routine. This passing of control from one 
recovery routine to another is called percolation. If none of the recovery routines can recover 
(request a retry), the control program terminates the process in control. 

When a recovery routine gets control, it determines why it has been entered and decides either 
to percolate or to retry. To tell RTM what it wants done, the recovery routine issues the 
SETRP macro instruction, which manipulates fields in the system diagnostic work area 
(SDWA). When the recovery routine returns to RTM, RTM honors the request, if possible. 

To allow communication between the main routine and the recovery routine, there is a 
parameter area. For a recovery routine established by an ESTAE macro instruction, you can 
supply a parameter area by coding the PARAM parameter on the macro instruction. When 
you establish a recovery routine, RTM saves a pointer to the parameter area and makes the 
pointer available to your recovery routine when it is entered. Usually, the main routine uses 
the parameter area to leave a footprint, that is, it sets indicators as part of normal processing; if 
an error occurs, these indicators let the recovery routine know where in the main process the 
failure occurred. The recovery routine can examine the footprint to determine what action to 
take. 

If the recovery routine decides that a retry might be successful, it asks RTM to continue 
execution of the main routine at some appropriate point. Note that retry is not always allowed. 
If a recovery routine requests a retry when retry is not allowed, RTM ignores the request and 
continues with the termination process (percolates). 

Any recovery routine that requests a retry must always include logic designed to avoid 
recursion, to prevent the creation of a tight loop between the recovery routine and the retry 
portion of the main routine. For example, if the recovery routine supplies a bad retry address 
to RTM, and the execution of the first instruction at the given address causes a program check, 
the first recovery routine to get control is the one that just requested the retry. If the recovery 
routine requests another retry at the same address, the loop is formed. 



1 Cross memory mode is described in SPL: System Macros and Facilities. 
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Using SETRP to Change the Completion and Reason Codes 

You can specify both completion and reason code values on the ABEND macro instruction. 
RTM passes these values to recovery exit routines to identify abnormal terminations. You can 
change the values of the completion code and the reason code by using the SETRP macro 
instruction. The COMPCOD keyword allows you to specify a new completion code; the 
REASON keyword allows you to specify a new reason code. 

The reason code has no meaning by itself, but must be used in conjunction with a completion 
code. In order to maintain meaningful completion and reason codes, RTM propagates changes 
to these values according to the following rules: 

• If a user changes both the completion code and the reason code, RTM accepts both new 
values. 

• If a user changes the reason code but not the completion code, RTM accepts the new 
reason code and uses the unchanged completion code. 

• If a user changes the completion code but not the reason code, RTM accepts the new 
completion code and uses a zero for the reason code. 

• If a user does not change either value, RTM uses the unchanged values. 

Changing the Completion and Reason Codes Directly 

Using the SETRP macro instruction is the preferred way for changing the completion and 4 

reason codes. If you change these values directly in a recovery exit routine you should emulate ™ 

SETRP processing as follows: 

• When you change the completion code, store the new completion code in SDWACMPC, a 
three-byte field in the system diagnostic word area (SDWA), and set the one-bit flag, 
SDWACCF, to indicate the change. 

• When you change the reason code, store the new reason code in SDWACRC, a four-byte 
field in the SDWA, and set the one-bit flag, SDWAREAF, to indicate the change. 

Before passing control to a recovery exit routine, RTM saves the current completion and reason 
codes. After the recovery routine returns control to RTM, RTM examines the contents of the 
SDWACCF and SDWAREAF flags to determine whether changes have been made to the 
completion and 

reason codes and then determines which values to pass to the next recovery exit routine. RTM 
makes this decision as shown in the following table: 

SDWACCF SDWAREAF Values passed to the 

Completion code flag Reason code flag next recovery exit routine 

ON OFF The abend completion code and a reason code of zero 

OFF ON The unchanged completion code and the altered reason code 

ON ON The altered completion code and the altered reason code 

If both flags are off, RTM passes the values in the user's SDWA to the next recovery exit 

routine unless the completion code has been changed and the reason code has not been 

changed. In this case RTM passes the value of the completion code in the user's SDWA and a d 

reason code of zero to the next recovery exit routine. ™ 
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Handling ABENDs 
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The control program does a great deal of checking for abnormal conditions. It uses hardware 
to detect errors such as protection violations or addressing errors. The data management and 
supervisor routines provide some error checking facilities to ensure that, based on the 
information you have provided, only valid data is being processed, and that you have not made 
any conflicting requests. For abnormal conditions that can possibly be corrected, the control 
program returns to your program with a return code indicating the probable source of the 
error. For conditions that indicate that further processing would result in degradation of the 
system or destruction of data, the control program gives control to RTM. 

There will, of course, be abnormal conditions unique to your program that the control program 
cannot detect. Figure 36 is an example of one of these. The routine shown in Figure 36 
checks a control field in an input parameter list to determine which function the program is to 
perform. Only characters 1 through 4 are valid in the control field. The presence of any other 
character is invalid, but the routine must be prepared to detect and handle these characters. 
One way to handle an invalid character is to return to the calling program with an error return 
code. The calling program can then try to interpret the return code and recover from the error. 
If it cannot do so, the calling program can detach its incomplete subtasks, execute its usual 
termination procedures, and return control to its calling program, again with an error return 
code. This procedure might result in termination of all the tasks of a job step; if it does, you 
can use the COND parameters of the JOB and EXEC statements to indicate whether 
subsequent job steps should be executed. 

Another way to handle this unexpected condition is to issue an ABEND macro instruction. 
RTM gets control. 

The position within the job step hierarchy of the task for which the ABEND macro instruction 
is issued determines the exact function of the abnormal termination routine. If an ABEND 
macro instruction is issued when the job step task (the highest level or only task) is active, or if 
the STEP parameter is coded in an ABEND macro instruction issued during the performance 
of any task in the job step, all the tasks in the job step are terminated. For example, if the 
STEP parameter is coded in an ABEND macro under TSO, the TSO job will be terminated. 
An ABEND macro instruction (without a STEP parameter) that is issued in performance of 
any task in the job step task usually causes only that task and its subtasks to be abnormally 
terminated. However, if the abnormal termination cannot be fulfilled as requested, it might be 
necessary for RTM to abnormally terminate the job step task. 



Program Interruption, Recovery /Termination, and Dumping Services 61 



Update \!?L 
(1) 



No 



Delete 
(2) 



No 



Copy 
(4) 



No 



Yes 



Create \ Yes 
(3) 



No 



Yes 



3 



RTN1 



D 



RTN2 



D 



RTN3 



r> 



RTN4 



D 



i 



Figure 36. Detecting an Abnormal Condition 

If you have created a recovery routine for your program, RTM passes control to your routine. 
If you have not set up a recovery routine, RTM handles the problem. The action RTM takes 
depends on whether or not the job step is going to be terminated. 

If the job step is not going to be terminated, RTM: 

• Releases the resources owned by the terminating task and all of its subtasks starting with 
the lowest level task. 

• Places the system or user completion code specified in the ABEND macro instruction in the 
task control block of the active task (the task for which the ABEND macro instruction was 
issued). 

• Posts the ECB with the completion code specified in the ABEND macro instruction if the 
ECB parameter was coded in the ATTACH macro instruction issued to create the active 
task. 
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• Schedules the end-of-task exit routine to be given control when the originating task 
becomes active if the ETXR parameter was coded in the ATTACH macro instruction 
issued to create the active task. 

• Calls a routine to FREEMAIN the terminating TCB. 
If the job step is to be terminated, RTM: 

• Releases the resources owned by each task, starting with the lowest level task, for all tasks 
in the job step. No end-of-task exit routine is given control. 

• Writes the system or user completion code specified in the ABEND macro instruction on 
the system output device. 

The remaining steps in the job are skipped unless you can establish your own recovery routine 
to perform similar functions and any other functions that your program requires. Use either 
the ESTAE macro instruction or the ATTACH macro instruction with the ESTAI option to set 
up an error routine that gets control whenever your program issues an ABEND macro 
instruction. Your error routine also gets control if the system issues an ABEND on your 
behalf. Your routine can determine its actions with regard to the abnormal condition. With 
this approach, you can put less error handling code in your mainline routines. For example, 
there is no need to check return codes after a subroutine if the subroutine issues an ABEND. 
The error handling functions can be part of the ESTAE or ESTAI routines that execute only 
when there is an error. 

How to Use an ESTAE Recovery Routine 

Within an ESTAE recovery routine, you can perform pre-termination functions and diagnose 
the error. You can also determine whether abnormal termination should continue for the task, 
or whether normal processing can continue at some point in the mainline routine. 

When the abnormal termination is issued, the ESTAE recovery routine must be resident. It can 
either be part of the program issuing the ESTAE or be brought into virtual storage with the 
LOAD macro instruction. 

A single program can create more than one recovery routine by issuing the ESTAE macro 
instruction with the CT parameter. (The program can also overlay or cancel recovery routines 
by issuing ESTAE macros with the OV parameter or with an address of zero, respectively.) All 
ESTAE requests issued by programs running under the same task are queued so that the 
routine established by the most recent ESTAE request is the first to get control. If this routine 
fails or requests that abnormal termination continue (percolation), RTM cancels the routine 
and the exit established by the previous ESTAE request gets control. 

If you want to use the same recovery routine for several tasks at the same time, the routine 
must be reenterable. For convenience, you should make all your ESTAE exit routines 
reenterable. 

You must cancel all the ESTAE routines you have created before returning control to your 
caller. If you try to cancel an ESTAE routine not associated with your request block, you get a 
return code that indicates your request is invalid. 
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Providing Information for Dump Analysis and Elimination 

Dump analysis and elimination (DAE) uses information that callers provide in ESTAE recovery 
routines to construct unique symptom strings needed to describe software failures. DAE uses 
these symptom strings to analyze dumps and suppress duplicates as requested. Each symptom 
string contains specific pieces of information called symptoms that DAE obtains from fields in 
the system diagnostic work area (SDWA), SDWA extensions, ABDUMP symptom area, and 
SDWA variable recording area (SDWAVRA). 

When using DAE, you must select symptoms carefully. If the data you supply is too precise, 
no other failure will have the same symptoms; if the data is too general, many failures will have 
the same symptoms. ; 

The following publications contain additional information pertaining to DAE: 

• SPL: System Modifications provides information about how an installation can modify 
DAE to fit its needs. 

• Operations: System Commands contains the syntax and use of the SET DAE command. 

• Debugging Handbook contains sample symptom output and DAE control block 
information. 

• System Logic Library provides a description of the logic and an explanation of symptom 
strings. 

• SPL: System Macros and Facilities Volume 1 describes the function of DAE for authorized 
users. 

Interface to an ESTAE Recovery Routine 

Before your first ESTAE recovery routine receives control, RTM performs I/O and 
asynchronous processing requests specified in the ESTAE macro instruction. RTM performs 
the requested I/O processing only for the first ESTAE routine. Subsequent routines receive an 
indication of the I/O processing previously done, but no additional processing is performed. 
However, RTM performs asynchronous processing for each routine. 

The recovery routine is enabled and has the same protection key and PSW key mask (PKM) as 
the routine that established the recovery routine as long as the establishing routine was under a 
problem program protection key (keys 8-15). An ESTAE routine created by a program running 
under key 0-7 gets control in key 0. 

Before each ESTAE recovery routine receives control, RTM tries to get storage for and to 
initialize a work area to contain information about the error. This work area is called the 
system diagnostic work area (SDWA). To access the SDWA, you must include the SDWA 
mapping macro - IHASDWA - as a DSECT in your ESTAE routine. Figure 37 shows key 
fields in the SDWA. 
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Field Name Use 

SDWAPARM This four-byte field, located at offset 0, contains the pointer to the user parameter list that you supply 
for an ESTAE-type recovery routine. 

SDWACMPC This three-byte field contains the ABEND completion code that existed when RTM gave control to 
the recovery routine. The recovery routine can change the ABEND code by changing this field. The 
system code appears in the first twelve bits and the user code appears in the second twelve bits. 

SDWAGRSV This field shows the contents of general registers 0-15 as they were at the time of the error. 

SDWACRC This four-byte field contains the reason code that existed when RTM entered the recovery routine. 

The recovery routine can change the reason code by changing this field. 

SDWAEC1 This field contains the PSW that existed at the time of the error. 

SDWAEC2 The contents of this field vary according to the type of recovery routine: 

• For an ESTAE routine, the field contains the extended control PSW of the RB that created the 
recovery routine at the time the RB last incurred an interruption. 

• For an ESTAI routine, this field contains zeroes. 
SDWASRSV The contents of this field vary according to the type of recovery routine. 

• For an ESTAE routine, this field contains the general registers 0-15 of the RB that established 
the recovery routine as they were at the time the RB last incurred an interruption. 

• For an ESTAI routine, this field contains zeroes. 

If the recovery routine requests a retry, RTM uses the contents of this field to load the registers for the 
retry routine. To change the contents of the registers for the retry routine, you must make the changes 
to this field and request a register update on the SETRP macro instruction. 

SDWASPID This field contains the subpool ID of the SDWA. 

SDWALNTH This field contains the length, in bytes, of the SDWA. 

SDWACOMU The recovery routines use this 8-byte field to communicate with each other when percolation occurs. 
RTM copies this field from one SDWA to the next on all percolations. If the field contains zeroes, 
either there was no information passed or RTM was not able to pass it. 

SDWAVRAL This field contains the length of the variable recording area (VRA) for this SDWA. 

SDWAHEX This is a one bit field set by the recovery routine to indicate that EREP is to print the data in the VRA 
in hexadecimal form. 

SDWAEBC This is a one-bit field set by the recovery routine to indicate that EREP is to print the data in the VRA 

in EBCDIC form. 

SDWAURAL This is a one-byte field set by the recovery routine to indicate the length of the VRA used. The field 
initially contains zeroes. Whenever the recovery routine uses any part of the VRA, it must set this 
field. 

SDWACCF The recovery routine sets this one-bit field when it changes the completion code. 

SDWAREAF The recovery routine sets this one-bit field when it changes the reason code. 

SDWAFAIN This 12-byte field contains the six bytes of the instruction stream that both precede and follow the 
failing instruction pointed to by the PSW. The SDWAFAIN field contains zeroes if RTM cannot 
access the failing instruction stream pointed to by the time-of-error PSW. For example, if the 
time-of-error PSW is not valid, the SDWAFAIN field contains zeroes. 

SDWADAET This eight-byte field contains DAE status and error flags for this dump. 

SDWAOCUR This two-byte field contains the current count of the number of previous occurrences of these 
symptoms in other SDWAs. 
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Figure 37. Key Fields in the SDWA 
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The first field in the SDWA contains the address of the parameter list established by the 
ESTAE macro instruction. The register contents on entry to the ESTAE routine depends on 
whether or not RTM obtained an SDWA. If RTM obtained an SDWA, the registers are as 
follows: 

Register A code indicating the type of I/O processing performed: 

— Active I/O has been quiesced and is restorable. 

4 — Active I/O has been halted and is not restorable. 

8 — No I/O was active when the ABEND occurred. 

16 — No I/O processing was performed. 

Register 1 Address of the SDWA. 

Registers 2-12 Unpredictable. 

Register 13 Address of a 72-byte register save area. 

Register 14 Return address. 

Register 15 Entry point address. 

When the ESTAE routine has completed its analysis of the error, it can use the SETRP macro 
instruction to inform RTM what it wants done. The SETRP macro instruction initializes the 
SDWA with the desired options. You can return from the ESTAE exit routine by using the 
SETRP REGS parameter or by using a BR 14 instruction. 

If RTM could not obtain an SDWA, the register contents are as follows: 

Register 12 (decimal). RTM could not obtain an SDWA. 

Register 1 ABEND completion code. 

Register 2 Address of the parameter list specified in the ESTAE macro instruction or 0. 

Registers 3-13 Unpredictable. 

Register 14 Return address. 

Register 15 Entry point address. 

If RTM could not provide an SDWA, it does not provide a register save area either. In this 
case, your ESTAE routine must save the address in register 14 and use it as the return address 
to RTM. You must place a return code in register 15 before returning to RTM. The return 
code indicates whether ABEND processing is to be continued for the task or whether a retry 
address can be given control. The return codes are: 

Return 

Code Meaning 

Continue with termination. Any ESTAE routines that were established prior to this routine will get control. 

4 Give control to the retry address. (You must place the retry address in register 0.) 



How to Use an ESTAI Routine 



You can provide an exit in your program to intercept abnormal termination of a subtask by 
using the ESTAI parameter on the ATTACH macro instruction you issue to create the subtask. 
Once you establish an ESTAI routine for one of your subtasks, it will be used for all of your 
subtasks. For example, suppose task A attaches task B and uses the ESTAI parameter in the 
ATTACH macro instruction. When task B attaches task C, the ESTAI routine created by task 
A is active for C as well as B. 

Because more then one subtask can abnormally terminate at the same time, the ESTAI routine 
might be used by more than one subtask concurrently. Your ESTAI exit routines must 
therefore be reenterable. 
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ESTAI routines are entered after all ESTAE routines that exist for a given task have received 
control and have either failed or percolated. The interface to ESTAI routines is the same as for 
ESTAE exits, however, one additional option is available for ESTAI. When you return to 
RTM, you can specify return code 16 either on the SETRP macro instruction if an SDWA 
exists, or in register 15 if an SDWA is not available. The return code indicates to RTM that 
termination should continue and that no other ESTAI routines should receive control for that 
task. 

ESTAE/ESTAI Retry Routines 

If a given ESTAE or ESTAI routine requests percolation, RTM gives control to the next oldest 
ESTAE or ESTAI routine that exists for the task. However, if a given ESTAE or ESTAI exit 
routine requests retry, the control program takes a dump if requested and does not process any 
further ESTAE or ESTAI routines. 

An ESTAE or ESTAI routine can request retry whenever the SDWACLUP bit in the SDWA is 
set to zero. To request retry, the exit routine must supply a retry address. The retry address is 
the point in the mainline routine that is to get control in order to continue its processing. In 
response to a valid retry request, RTM gives control to the retry address supplied. A retry 
routine requested by an ESTAE routine operates as an extension of the mainline code. That is, 
the retry routine operates under the same RB that issued the request for ESTAE recovery. All 
RBs prior to the retry RB are purged before giving control to the retry routine. 

RTM purges the RB queue to cancel the effects of partially executed programs that are at a 
lower level in the program hierarchy than the program for which the retry occurs. Certain 
effects, however, cannot be canceled. Among these are: 

• Subtasks created by an RB to be purged 

• Resources allocated by the ENQ macro instruction 

• DCBs that exist in dynamically-acquired virtual storage 

If there are quiesced restorable I/O operations, the retry routine can restore them. RTM 
supplies a pointer to the purged I/O request list. You can use SVC RESTORE to have the 
control program restore all I/O requests on the list. The retry routine should free the storage 
occupied by the SDWA (if there was an SDWA) when that storage is no longer needed unless 
the exit routine specified FRESDWA=YES on the SETRP macro instruction. The subpool 
number and length to use on the FREEMAIN macro instruction are in the SDWA. 

Interface to a Retry Routine 

There are two different interfaces to a retry routine: 

• If RTM was able to obtain an SDWA, you can set the register contents in the SDWA to 
whatever you wish and request that they be passed to the retry routine by coding 
RETREGS=YES in the SETRP macro instruction. This method is used most often in 
mainline processing. 

• If RTM could not obtain an SDWA or if RETREGS = NO was specified on the SETRP 
macro instruction, only parameter registers are passed to the retry routine. This method is 
used most often if a special retry routine is to get control. 
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If RTM could not obtain an SDWA, register contents are as follows: 

Register 12 (decimal) 

Register 1 Address of the user parameter list established via the ESTAE macro instruction 

Register 2 Address of the purge I/O restore list (PIRL) if I/O was quiesced and is restorable, otherwise 

Registers 3-13 Unpredictable 

Register 14 Address of an SVC 3 instruction 

Register 15 Entry point address of the retry routine 

If RTM obtained an SDWA and the retry routine specified RETREGS = NO or 
FRESDWA = NO: 

Register 

Register 1 Address of the SDWA 

Registers 2-13 Unpredictable 

Register 14 Address of an SVC 3 instruction 

Register 15 Entry point address of the retry routine 

If RTM obtained an SDWA and the retry routine specified RETREGS=NO and 
FRESDWA = YES: 

Register 20 (decimal) 

Register 1 Address of the user parameter list established via the ESTAE macro instruction 

Register 2 Address of the PIRL if I/O was quiesced and is restorable, otherwise 

Registers 3-13 Unpredictable 

Register 14 Address of an SVC 3 instruction 

Register 15 Entry point address of the retry routine 

If the retry routine requested register update (RETREGS = YES), the registers, as they appear 
in the SDWA, are passed to the retry routine. 

In all cases, the routine runs enabled and the protection key is the same key as the routine that 
established the retry routine. 



Dumping Services 



A problem program can request two types of storage dumps: 

• An ABEND dump obtained through use of the DUMP parameter in the ABEND macro 
instruction or the DUMP = YES parameter on the SETRP macro instruction in a recovery 
exit. 

• A snap dump obtained through use of the SNAP macro instruction. 



ABEND Dumps 



An ABEND macro instruction initiates error processing for a task. The DUMP option of 
ABEND requests a dump of storage and the DUMPOPT option may be used to specify the 
areas to be displayed. These dump options may be expanded by an ESTAE or EST AI routine. 
The control program usually requests a dump for you when it issues an ABEND macro 
instruction. However, the control program can provide an ABEND dump only if you include a 
DD statement (SYSABEND, SYSMDUMP, or SYSUDUMP) in the job step. The DD 
statement determines the type of dump provided and the system dump options that are used. 
When the dump is taken, the dump options that you requested (specified in the ABEND macro 
instruction or by recovery routines) are added to the installation-selected options. 
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Note: The operator can use the CHNGDUMP command either to alter the dump options you 
or the installation specified, or to suppress all ABEND dumps. 

If a dump is requested and the ESTAE/ESTAI routine also requests retry, the control program 
takes the dump before passing control to the retry address. 

The data set containing the dump can reside on any device supported by the basic sequential 
access method (BSAM). The dump is placed in the data set described by the DD statement you 
provide. If you select a printer, the dump is printed immediately. However, if you select a 
direct access or tape device, you must schedule a separate job to obtain a listing of the dump, 
and to release the space on the device. If the dump data set was described by a SYSMDUMP 
DD statement, you can use the AMDPRDMP service aid to format and print the dump. (Do 
not select a printer for a SYSMDUMP DD statement.) For information about the 
AMDPRDMP service aid see SPL: Service Aids. 



Obtaining a Symptom Dump 



With all ABEND dumps, you will automatically receive a short symptom dump of 
approximately ten lines. This symptom dump provides a summary of error information, which 
will help you to identify duplicate problems. 

You will receive this dump even without a DD statement unless your installation changes the 
default via the CHNGDUMP operator command or the dump parmlib member for 
SYSUDUMP. 
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SNAP Dumps 
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A task can request a SNAP dump at any time during its processing by issuing a SNAP macro 
instruction. For a SNAP dump, the DD statement can have any name except SYSABEND, 
SYSMDUMP, and SYSUDUMP. 

Like the ABEND dump, the data set containing the dump can reside on any device that is 
supported by BSAM. The dump is placed in the data set described by the DD statement you 
provide. If you select a printer, the dump is printed immediately. However, if you select a 
direct access or tape device, you must schedule a separate job to obtain a listing of the dump, 
and to release the space on the device. 

To obtain a dump using the SNAP macro instruction, you must provide a data control block 
and issue an OPEN macro instruction for the data set before issuing any SNAP macro 
instructions. If the standard dump format is requested, 120 characters per line are printed. The 
data control block must contain the following parameters: DSORG = PS, RECFM = VBA, 
MACRF=W, BLKSIZE = 882 or 1632, and LRECL= 125. (The data control block is 
described in Data Management Services Guide and Data Management Macro Instructions. If a 
high-density dump is to be printed on a 3800 Printing Subsystem, 204 characters per line are 
printed. To obtain a high-density dump, code CHARS = DUMP on the DD statement 
describing the dump data set. The BLKSIZE= must be either 1470 or 2724, and the 
LRECL= must be 209. CHARS = DUMP can also be coded on the DD statement describing 
a dump data set that will not be printed immediately. If CHARS = DUMP is specified and the 
output device is not a 3800, print lines are truncated and print data is lost. If your program is 
to be processed by the loader, you should also issue a CLOSE macro instruction for the SNAP 
data control block. 
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Finding Information in a SNAP Dump 



You will obtain a dump index with each SNAP dump. The index will help you find 
information in the dump more quickly. Included in the information in the dump index is an 
alphabetical list of the active load modules in the dump along with the page number in the 
dump where each starts. 



Obtaining a Summary Dump 



You can request a summary dump for an abending task by coding the SUM option of the 
SNAP macro instruction. You can also obtain a summary dump by coding the DUMPOPT 
option of the ABEND or SETRP macro instruction and specifying a list form of SNAP that 
contains the SUM option. 

If SUM is the only option that you specify, the dump will contain a dump header, control 
blocks, and the other areas listed below. The dump header for all ABEND dumps contains the 
following information: 

• The dump title 

• The ABEND code and program status word (PSW) at the time of the error 

• If the PSW contains the address of an active load module: 

- The name and address from the PSW of the load module in error 

- The offset, into this load module, at which the error occurred 

The control blocks and other areas consist of the following information: 

• The control blocks dumped for the CB option 

• The error control blocks (RTM2WAs and SCBs) 

• The save areas 

• The registers at the time of the error 

• The contents of the load module (if the PSW contains the address of an active load 
module) 

• The module pointed to by the last PRB (if it can be found) 

• IK of storage before and after the addresses pointed to by the PSW and the registers at the 
time of the error 

Note: This storage will only be dumped if the caller is authorized to obtain it. The storage 
is printed by ascending storage addresses, with duplicate addresses removed. 

• The supervisor trace table consisting of all trace entries for the ASID that is being dumped. 
Note: The GTF trace records are not included in the dump. 
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If you specify other options in addition to SUM, the summary dump is dispersed throughout 
the dump. For example, if you specify the options: 

CB , SUM , SPLS , LSQA , ERR , TRT 

The dump will contain the following information: 

Dump title (SUM) 

ABEND code and PSW (SUM) 

Name and address from the PSW of the module in error (SUM) 

Offset into the module where the error occurred (SUM) 

Control blocks (SUM and CB) 

Error control blocks (ERR) 

Save areas (SUM) 

LSQA (LSQA) 

Registers at the time of the error (SUM) 

Contents of the active load module (SUM) 

IK of storage before and after the addresses in the PSW and the registers at the time of the 
error (SUM) 

Subpool data (SPLS) 

If system trace is active, the system trace data and if GTF is active, the GTF trace data 
(TRT) 
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Virtual Storage Management 
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Use the virtual storage area assigned to your job step through implicit and explicit requests for 
virtual storage. The use of a LINK macro instruction is an example of an implicit request; the 
control program allocates storage before bringing the load module into your job pack area. 
The use of the GETMAIN macro instruction is an explicit request for a certain number of 
bytes of virtual storage to be allocated to the active task. In addition to your requests for 
virtual storage, requests are made by the control program and data management routines for 
areas to contain some of the control blocks required to manage your tasks. 

Note: If your job step is to be executed as a nonpageable (V = R) task, the REGION 
parameter value specified on the job or execute statement determines the amount of virtual 
(real) storage reserved for the job step. If you run out of storage because of a system failure, 
such as in a GETMAIN request, increase the REGION parameter size. 

The following paragraphs discuss some of the techniques that can be applied for efficient use of 
the virtual storage area reserved for your job step. These techniques apply as well to the data 
management portions of your programs. The specific data management storage allocation 
facilities are discussed in the Data Management Services Guide and Data Management Macro 
Instructions publications; the principles discussed here provide the background you need to use 
these facilities. 



Explicit Requests for Virtual Storage 



Virtual storage can be explicitly requested for the use of the active task by issuing a GETMAIN 
macro instruction. The request is satisfied by allocating a portion of the virtual storage area 
reserved for the job step. The virtual storage area is usually not set to zero when allocated. 
(The storage is zeroed for the initial allocation of a page). 

You release virtual storage by issuing a FREEMAIN macro instruction. This does not release 
the area from control of the job step, but makes the area available to satisfy the requirements 
of additional requests for any task in the job step. The virtual storage assigned to a task is also 
given up to a different task in the same job step when the task terminates, except as indicated 
under "Subpool Handling." Releasing virtual storage for use by other job steps is discussed 
under "Relinquishing Virtual Storage." 



Specifying the Size of the Area 
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Virtual storage areas are always allocated to the task in multiples of eight bytes and may begin 
on either a doubleword or page boundary. The request for virtual storage is given in terms of 
bytes; if the number specified is not a multiple of eight, it is rounded to the next higher multiple 
of eight. You can make repeated requests for a small number of bytes as you need the area or 
you can make one large request to completely satisfy the requirements of the task. There are 
two reasons for making one large request: it is the only way you can be sure of getting 
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contiguous storage and avoid fragmenting your address space, and because you only make one 
request, the amount of control program overhead is less. 



Types of Explicit Requests 



There are several methods of explicitly requesting virtual storage using a GETMAIN macro 
instruction. Each of the methods, which are designated by coding an associated character in 
the parameter field of the GETMAIN macro instruction, has certain advantages, depending on 
the requirements of your program. You can specify the actual location (above or below 16 Mb) 
of the virtual area allocated by using the LOC parameter of the GETMAIN macro instruction. 
(LOC is valid only with RU, RC, VRU, and VRC.) If you code LOC = ANY and the subpool 
indicated is supported above 16 Mb, GETMAIN attempts to allocate the virtual storage area 
above 16 Mb. If this is not possible or if the subpool is not supported above 16 Mb, 
GETMAIN allocates the area below 16 Mb. 

The last three methods do not produce reenterable coding unless coded in the list and execute 
forms. (See the topic "Implicit Requests" for additional information.) When you use the last 
three types, you can allocate storage below 16 Mb only. 

The methods and the characters associated with them follow: 

Register Type: There are several kinds of register requests. In each case the address of the 
area is returned in register 1. All of the register requests produce reenterable code because the 
parameters are passed to the control program in registers, not in a parameter list. The register 
requests are as follows: 

R specifies a request for a single area of virtual storage of a specified length, located below 16 Mb. , 

J 
RU or RC specifies a request for a single area of virtual storage of a specified length, located above or below 16 ^ 

Mb according to the LOC parameter. 

VRU or VRC specifies a request for a single area of virtual storage with length between two values that you specify, 
located above or below 16 Mb according to the LOC parameter. GETMAIN attempts to allocate the 
maximum length you specify. If not enough storage is available to allocate the maximum length, 
GETMAIN allocates the largest area with a length between the two values that you specified. 
GETMAIN returns the length in register 0. 

Element Type: EC or EU specifies a request for a single area of virtual storage, below 16 Mb, 
of a specified length. GETMAIN places the address of the allocated area in a fullword that 
you supply. 

Variable Type: VC or VU specifies a request for a single area of virtual storage below 16 Mb 
with a length between two values you specify. GETMAIN attempts to allocate the maximum 
length you specify; if not enough storage is available to allocate the maximum length, the 
largest area with a length between the two values is allocated. GETMAIN places the address of 
the area and the length allocated in two consecutive fullwords that you supply. 

List Type: LC or LU specifies a request for one or more areas of virtual storage, below 16 
Mb, of specified lengths. 

In addition to the above methods of requesting virtual storage, you can designate the request as 

conditional or unconditional. If the request is unconditional and sufficient virtual storage is not 

available to fill the request, the active task is abnormally terminated. If the request is 

conditional, however, and insufficient virtual storage is available, a return code of 4 is provided 

in register 15; a return code of is provided if the request was satisfied. ■ 
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An example of using the GETMAIN macro instruction is shown in Figure 38. The example 
assumes a program that operates most efficiently with a work area of 16,000 bytes, with a fair 
degree of efficiency with 8,000 bytes or more, inefficiently with less than 8,000 bytes. The 
program uses a reenterable load module having an entry name of REENTMOD, and will use it 
again later in the program; to save time, the load module was brought into the job pack area 
using a LOAD macro instruction so that it will be available when it is required. 
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Figure 38. Using the GETMAIN Macro Instruction 

A conditional request for a single element of storage with a length of 16,000 bytes is requested 
in Figure 38. The return code in register 15 is tested to determine if the storage is available; if 
the return code is (the 16,000 bytes were allocated), control is passed to the processing 
routine. If sufficient storage is not available, an attempt to obtain more virtual storage is made 
by issuing a DELETE macro instruction to free the area occupied by the load module 
REENTMOD. A second GETMAIN macro instruction is issued, this time an unconditional 
request for an area between 4,000 and 16,000 bytes in length. If the minimum size is not 
available, the task is abnormally terminated. If at least 4,000 bytes are available, the task can 
continue. The size of the area actually allocated is determined, and one of the two procedures 
(efficient or inefficient) is given control. 



Cell Pool Services 



The cell pool macro instruction (CPOOL) provides users with another way of obtaining virtual 
storage. This macro instruction provides centralized, high performance cell management 
services. 

Cell pool services obtain a block of virtual storage (called a cell pool) from a specified subpool 
at the user's request. The user can then request smaller blocks of storage (called cells) from this 
cell pool as needed. If the storage for the requested cells exceeds the storage available in the 
cell pool, the user can also request that the cell pool be increased in size (extended) to fill all 
requests. 
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The CPOOL macro instruction provides the user with the following cell pool services: 

• Create a cell pool (BUILD) ( 

• Obtain a cell from a cell pool if storage is available (GET,COND) 

• Obtain a cell from a cell pool and extend the cell pool if storage is not available 
(GET,UNCOND) 

• Return a cell to the cell pool (FREE) 

• Free all storage for a cell pool (DELETE) 

Subpool Handling 

In an operating system, subpools of virtual storage are provided to assist in virtual storage 
management and for communications between tasks in the same job step. Because the use of 
subpools requires some knowledge of how the control program manages virtual storage, a 
discussion of virtual storage control is presented here. 

Virtual Storage Control: When the job step is given a region of virtual storage, all of the 
storage area available for your use within that region is unassigned. Subpools are created only 
when a GETMAIN macro instruction is issued designating a subpool number (other than 0) 
not previously specified. If no subpool number is designated, the virtual storage is allocated 
from subpool 0, which is created for the job step by the control program when the job-step task 
is initiated. 

The PSW key of the requestor is assigned to the subpool and does not change. A task, if it is | 

authorized to do so, can change its PSW key. Such a change makes a previously acquired 
subpool unusable because the subpool's key no longer matches the task's key. 

For purposes of control and virtual storage protection, the control program considers all virtual 
storage within the region in terms of 4096-byte blocks. These blocks are assigned to a subpool, 
and space within the blocks is allocated to a task by the control program when requests for 
virtual storage are made. When there is sufficient unallocated virtual storage within any block 
assigned to the designated subpool to fill a request, the virtual storage is allocated to the active 
task from that block. If there is insufficient unallocated virtual storage within any block 
assigned to the subpool, a new block (or blocks, depending on the size of the request) is 
assigned to the subpool, and the storage is allocated to the active task. The blocks assigned to 
a subpool are not necessarily contiguous unless they are assigned as a result of one request. 
Only blocks within the region reserved for the associated job step can be assigned to a subpool. 

Figure 39 is a simplified view of a virtual-storage region containing four 4096-byte blocks of 

storage. All the requests are for virtual storage from subpool 0. The first request from some 

task in the job step is for 1008 bytes; the request is satisfied from the block shown as Block A 

in the figure. The second request, for 4000 bytes, is too large to be satisfied from the unused 

portion of Block A, so the control program assigns the next available block, Block B, to 

subpool 0, and allocates 4000 bytes from Block B to the active task. A third request is then 

received, this time for 2000 bytes. There is enough area in Block A (blocks are checked in the 

order first in, first out), so an additional 2000 bytes are allocated to the task from Block A. All 

blocks are searched for the closest fitting free area which will then be assigned. If the request 

had been for 96 bytes or less, it would have been allocated from Block B. Because all tasks 

may share subpool 0, Request 1 and Request 3 do not have to be made from the same task, ■ 

even though the areas are contiguous and from the same 4096 byte block. Request 4, for 6000 ^ 
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bytes, requires that the control program allocate the area from 2 contiguous blocks which were 
previously unassigned, Block D and Block C. These blocks are assigned to subpool 0. 
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Figure 39. Virtual Storage Control 

As indicated in the preceding example, it is possible for one 4096-byte block in subpool to 
contain many small areas allocated to many different tasks in the job step, and it is possible 
that numerous blocks could be split up in this manner. Areas acquired by a task other than the 
job-step task are not released automatically on task termination. Even if FREEMAIN macro 
instructions were issued for each of the small areas before a task terminated, the probable result 
would be that many small unused areas would exist within each block while the control 
program would be continually assigning new blocks to satisfy new requests. To avoid this 
situation, you can define subpools for exclusive use by individual tasks. 

Any subpool can be used exclusively by a single task or shared by several tasks. Each time that 
you create a task, you can specify which subpools are to be shared. Unlike other subpools, 
subpool is shared by a task and its subtask, unless you specify otherwise. When subpool is 
not shared, the control program creates a new subpool for use by the subtask. As a result, 
both the task and its subtask can request storage from subpool but both will not receive 
storage from the same 4096-byte block. When the subtask terminates, its virtual storage areas 
in subpool are released; since no other tasks share this subpool, complete 4096-byte blocks are 
made available for reallocation. 

Note: If the storage is shared, it is not released until the owning task terminates. 



w 



When there is a need to share subpool 0, you can define other subpools for exclusive use by 
individual tasks. When you first request storage from a subpool other than subpool 0, the 
control program assigns a new 4096-byte block to that subpool, and allocates storage from that 
block. The task that is then active is assigned ownership of the subpool and, therefore, of the 
block. When additional requests are made by the same task for the same subpool, the requests 
are satisfied by allocating areas from that block and as many additional blocks as are required. 
If another task is active when a request is made with the same subpool number, the control 
program assigns a new block to a new subpool, allocates storage from the new block, and 
assigns ownership of the new subpool to the second task. 
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A task can specify subpools numbered from to 127. FREEMAIN macro instructions can be 
issued to release any complete subpool except subpool 0, thus releasing complete 4096-byte 
blocks. When a task terminates, its unshared subpools are released automatically. 

Owning and Sharing: A subpool is initially owned by the task that was active when the 
subpool was created. The subpool can be shared with other tasks, and ownership of the 
subpool can be assigned to other tasks. Two macro instructions are used in the handling of 
subpools: the GETMAIN macro instruction and the ATTACH macro instruction. In the 
GETMAIN macro instruction, the SP parameter can be written to request storage from 
subpools to 127; if this parameter is omitted, subpool is assumed. The parameters that deal 
with subpools in the ATTACH macro instruction are: 

• GSPV and GSPL, which give ownership of one or more subpools (other than subpool 0) to 
the task being created. 

• SHSPV and SHSPL, which share ownership of one or more subpools (other than subpool 
0) with the new subtask. 

• SZERO, which determines whether subpool is shared with the subtask. 

All of these parameters are optional. If they are omitted, no subpools are given to the subtask, 
and only subpool is shared. 

Creating a Subpool: If the subpool specified does not exist for the active task, a new subpool is 
created whenever SHSPV or SHSPL is coded on an ATTACH macro instructions or a 
GETMAIN macro instruction is issued. A new subpool zero is created for the subtask if 
SZERO = NO is specified on ATTACH. If one of the ATTACH macro instruction parameters 
that specifies shared ownership of a subpool causes the subpool to be created, the subpool 
number is entered in the list of subpools owned by the task, but no blocks are assigned and no 
storage is actually allocated. If a GETMAIN macro instruction results in the creation of a 
subpool, the subpool number is assigned to one or more 4096-byte blocks, and the requested 
storage is allocated to the active task. In either case, ownership of the subpool belongs to the 
active task; if the subpool is created because of an ATTACH macro instruction, ownership is 
transferred or retained depending on the parameter used. 

Transferring Ownership: An owning task gives ownership of a subpool to a direct subtask by 
using the GSPV or GSPL parameters in the ATTACH macro instruction issued when that 
subtask is created. Ownership of a subpool can be given to any subtask of any task, regardless 
of the control level of the two tasks involved and regardless of how ownership was obtained. A 
subpool cannot be shared with one or more subtasks and then transferred to another subtask, 
however; an attempt to do this results in abnormal termination of the active task. Ownership 
of a subpool can only be transferred if the active task has sole ownership; if the active task is 
sharing a subpool and an attempt is made to transfer it to a subtask, the subtask receives 
shared control and the originating task relinquishes the subpool. Once ownership is transferred 
to a subtask or relinquished, any subsequent use of that subpool number by the originating task 
results in the creation of a new subpool. When a task that has ownership of one or more 
subpools terminates, all of the virtual storage areas in those subpools are released. Therefore, 
the task with ownership of a subpool should not terminate until all tasks or subtasks sharing 
the subpool have completed their use of the subpool. 

If GSPV or GSPL specifies a subpool which does not exist for the active task, no action is 
taken. 
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Sharing a Subpool: Shared use of a subpool can be given to a direct subtask of any task with 
ownership or shared control of the subpool. Shared use is given by specifying the SHSPV or 
SHSPL parameters in the ATTACH macro instruction issued when the subtask is created. Any 
task with ownership or shared control of the subpool can add to or reduce the size of the 
subpool through the use of GETMAIN and FREEMAIN macro instructions. When a task 
that has shared control of the subpool terminates, the subpool is not affected. 

Subpools in Task Communication: The advantage of subpools in virtual storage management is 
that, by assigning separate subpools to separate subtasks, the breakdown of virtual storage into 
small fragments is reduced. An additional benefit from the use of subpools can be realized in 
task communication. A subpool can be created for an originating task and all parameters to be 
passed to the subtask placed in the subpool. When the subtask is created, the ownership of the 
subpool can be passed to the subtask. After all parameters have been acquired by the subtask, 
a FREEMAIN macro instruction can be issued, under control of the subtask, to release the 
subpool virtual storage areas. In a similar manner, a second subpool can be created for the 
originating task, to be used as an answer area in the performance of the subtask. When the 
subtask is created, the subpool ownership would be shared with the subtask. Before the subtask 
is terminated, all parameters to be passed to the originating task are placed in the subpool area; 
when the subtask is terminated, the subpool is not released, and the originating task can acquire 
the parameters. After all parameters have been acquired for the originating task, a 
FREEMAIN macro instruction again makes the area available for reuse. 



Implicit Requests for Virtual Storage 
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You make an implicit request for virtual storage every time you issue a LINK, LOAD, 
ATTACH, or XCTL macro instruction. In addition, you make an implicit request for virtual 
storage when you issue an OPEN macro instruction for a data set. This section discusses some 
of the techniques you can use to cut down on the amount of real storage required by a job step, 
and the assistance given you by the control program. 



Reenterable Load Modules 



A reenterable load module is designed so that during execution it does not modify itself. Only 
one copy of the load module is paged into real storage to satisfy the requirements of any 
number of tasks in a job step. This means that even though there are several tasks in the job 
step and each task concurrently uses the load module, the only real storage needed is an area 
large enough to hold one copy of the load module (plus a few bytes for control blocks). The 
same amount of real storage would be needed if the load module were serially reusable; 
however, the load module could not be used by more than one task at a time. 



Reenterable Macro Instructions 
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All of the macro instructions described in this manual can be written in reenterable form. 
These macro instructions are classified as one of two types: macro instructions that pass 
parameters in registers and 1, and macro instructions that pass parameters in a list. The 
macro instructions that pass parameters in registers present no problem in a reenterable 
program; when the macro instruction is coded, the required parameter values should be 
contained in registers. For example, the POST macro instruction requires that the ECB address 
be coded as follows: 

POST ecb address 
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One method of coding this in a reenterable program would be to require this address to refer to 
a portion of storage that has been allocated to the active task through the use of a GETMAIN 
macro instruction. The address would change for each use of the load module. Therefore, you 
would load one of the general registers 2-12 with the address, and designate that register when 
you code the macro instruction. If register 4 contains the ECB address, the POST macro 
instruction is written as follows: 

POST (4) 

The macro instructions that pass parameters in a list require the use of special forms of the 
macro instruction when used in a reenterable program. The macro instructions that pass 
parameters in a list are identified within their descriptions in the macro instruction section of 
this manual. The expansion of the standard form of these macro instructions results in an 
in-line parameter list and executable instructions to branch around the list, to load the address 
of the list, and to pass control to the required control program routine. The expansions of the 
list and execute forms of the macro instruction simply divide the functions provided in the 
standard form expansion: the list form provides only the parameter list, and the execute form 
provides executable instructions to modify the list and pass control. You provide the 
instructions to load the address of the list into a register. 

The list and execute forms of a macro instruction are used in conjunction to provide the same 
services available from the standard form of the macro instruction. The advantages of using list 
and execute forms are as follows: 

• Any parameters that remain constant in every use of the macro instruction can be coded in 
the list form. These parameters can then be omitted in each of the execute forms of the 
macro instruction which use the list. This can save appreciable coding time when you use a 
macro instruction many times. (Any exceptions to this rule are listed in the description of 
the execute form of the applicable macro instruction.) 

• The execute form of the macro instruction can modify any of the parameters previously 
designated. (Again, there are exceptions to this rule.) 

• The list used by the execute form of the macro instruction can be located in a portion of 
virtual storage assigned to the task through the use of the GETMAIN macro instruction. 
This ensures that the program remains reenterable. 

Figure 40 shows the use of the list and execute forms of a DEQ macro instruction in a 
reenterable program. The length of the list constructed by the list form of the macro 
instruction is obtained by subtracting two symbolic addresses; virtual storage is allocated and 
the list is moved into the allocated area. The execute form of the DEQ macro instruction does 
not modify any of the parameters in the list form. The list had to be moved to allocated 
storage because the control program can store a return code in the list when RET = HAVE is 
coded. Note that the coding in a routine labeled MOVERTN is valid for lengths up to 256 
bytes only. Some macro instructions do produce lists greater than 256 bytes when many 
parameters are coded (for example, OPEN and CLOSE with many data control blocks, or ENQ 
and DEQ with many resources), so in actual practice a length check should be made. The 
move long instruction (MVCL) should be considered for moving large data lists. 



( 
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LA 


3,MACNAME 


LA 


5,NSIADDR 


SR 


5,3 


BAL 


14, MOVERTN 


DEQ 


,MF=(E,(1) ) 



Load address of list form 
Load address of end of list 
Length to be moved in register 5 
Go to routine to move list 
Release allocated resource 
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* The MOVERTN allocates storage from subpool and moves up to 256 

* bytes into the allocated area. Register 3 is from address, 

* register 5 is length. Area address returned in register 1. 



Address of area in register 4 
Subtract 1 from area length 
Move list to allocated area 
Return 
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Instruction in a Reenterable Program 

Figure 40. Using the List and the Execute Forms of the DEQ Macro 



Nonreenterable Load Modules 



The use of reenterable load modules does not automatically conserve virtual storage; in many 
applications it will actually prove wasteful. If a load module is not used in many jobs and if it 
is not employed by more than one task in a job step, there is no reason to make the load 
module reenterable. The allocation of virtual storage for the purpose of moving coding from 
the load module to the allocated area is a waste of both time and virtual storage when only one 
task requires the use of the load module. 

You should not make a load module reenterable or serially reusable if reusability is not really 
important to the logic of your program. Of course, if reusability is important, you can issue a 
LOAD macro instruction to load a reusable module, and later issue a DELETE macro 
instruction to release its area. 

Notes: 
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1. If your module is reenterable or serially reusable, the load module must be link edited, with 
the desired attribute, into a library. 

2. A module that does not modify itself (a refreshable module) reduces paging activity because it 
does not need to be paged out. 
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Freeing of Virtual Storage 



The control program establishes two responsibility counts for every load module brought into 
virtual storage in response to your requests for that load module. The responsibility counts are 
lowered as follows: 

• If the load module was requested in a LOAD macro instruction, that responsibility count is 
lowered when using a DELETE macro instruction. 

• If the load module was requested in a LINK, ATTACH, or XCTL macro instruction, that 
responsibility count is lowered when using an XCTL macro instruction or by returning 
control to the control program. 

• When a task is terminated, the responsibility counts are lowered by the number of requests 
for the load module made in LINK, LOAD, ATTACH, and XCTL macro instructions 
during the performance of that task, minus the number of deletions indicated above. 

The virtual storage area occupied by a load module is released when the responsibility counts 
reach zero. When you plan your program, you can design the load modules to give you the 
best trade-off between execution time and efficient paging. If you use a load module many 
times in the course of a job step, issue a LOAD macro instruction to bring it into virtual 
storage; do not issue a DELETE macro instruction until the load module is no longer needed. 
Conversely, if a load module is used only once during the job step, or if its uses are widely 
separated, issue a LINK macro instruction to obtain the module and issue an XCTL from the 
module (or return control to the control program) after it has been executed. 

There is a minor problem involved in the deletion of load modules containing data control 
blocks. An OPEN macro instruction must be issued before the data control block is used, and 
a CLOSE macro instruction issued when it is no longer needed. If you do not issue a CLOSE 
macro instruction for the data control block, the control program issues one for you when the 
task is terminated. However, if the load module containing the data control block has been 
removed from virtual storage, the attempt to issue the CLOSE macro instruction causes 
abnormal termination of the task. You must either issue the CLOSE macro instruction yourself 
before deleting the load module, or ensure that the data control block is still in virtual storage 
when the task is terminated (possibly by issuing a GETMAIN and creating the DCB in the area 
that had been allocated by the GETMAIN). 



< 



82 Supervisor Services and Macro Instructions 



Data-in-Virtual 



Data-in-virtual simplifies the writing of applications that use large amounts of data from 
permanent storage. Applications can create, read, and update data without the I/O buffer, 
blocksize, and record considerations that the traditional GET and PUT types of access methods 
require. Moreover, by using the services of data-in-virtual, certain applications that access large 
amounts of data can potentially improve their performance and their use of system resources. 

Such applications have an accessing pattern that is non-sequential and unpredictable. This kind 
of pattern is a function of conditions and values that are revealed only in the course of the 
processing. In these applications, the sequential record subdivisions of conventional access 
methods are meaningless to the central processing algorithm. It is difficult to adapt this class of 
applications to conventional record management programming techniques, which require all 
permanent storage access to be fundamentally record-oriented. Through the DIV macro, 
data-in-virtual provides these applications a way to manipulate the data without the constraints 
of record-oriented processing. 
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An application written for data-in-virtual views its permanent storage data as a seamless body 
of data without internal record boundaries. By using the data-in-virtual MAP service, the 
application can make any portion of the data set appear in virtual storage, in an area that is 
called a virtual storage window. Then, the data in the window can be referenced and updated 
with conventional processor instructions that access memory. When the application decides to 
copy the updates to the data set, it uses the data-in-virtual SAVE service. 
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The data-in-virtual services process the application data in 4096-byte units that are on page 
(4096-byte) boundaries. The processing is similar to that of paging data set support, but a 
special type of permanent data set is used to store the application data. This type of data set, 
which is called a linear data set, is supported by Access Method Services and is referred to in 
this book as a data-in-virtual object, a data object, or simply, an object. The data-in-virtual 
object is truly a continuous string of uninterrupted data. 



Data-in- Virtual 83 



Defining a Linear Data Set 



Before you can use the DIV macro to process a linear data set, the data set must exist on 
permanent storage. 

To create the data set, you need to specify the DEFINE CLUSTER function of IDCAMS with 
the LINEAR parameter. When you use DEFINE CLUSTER, it is strongly recommended that 
you specify the SHAREOPTIONS(l,3) parameter with a dataset disposition parameter of ,SHR 
in the JCL. This permits multiple readers or a single updater to access the linear data set. The 
system does not provide suitable data set integrity if any other values are specified for 
SHAREOPTIONS. 

The following JCL invokes Access Method Services (IDCAMS) to create the linear data set 
named DIV. SAMPLE on the volume called DIVPAK. When IDCAMS creates the data set, it 
creates it as an empty data set. Note that no RECORDS parameter is used because linear data 
sets do not have records. 



//JNAME 


JOB ' ALLOCATE LINEAR ' ,MSGLEVEL= (1,1), 


// 


CLASS=R , MSGCLASS=D , USER= JOHNDOE 


//* 




//* 




//* 


ALLOCATE A VSAM LINEAR DATASET 


//* 




//CLUSTPG 


EXEC PGM=IDCAMS,REGION=4096K 


//SYSPRINT 


DD SYSOUT=* 


//DIVPAK 


DD UNIT=3380,VOL=SER=DIVPAK,DISP=OLD 


//SYSIN 


DD * 




DEFINE CLUSTER (NAME (DIV. SAMPLE) - 




VOLUMES (DIVPAK) - 




TRACKS (1,1) - 




SHAREOPTIONS ( 1 , 3 ) - 




LINEAR) 


/* 





For further information on the creation of linear VSAM data sets and the alteration of 
entry-sequenced VSAM data sets, see MVSI Extended Architecture Integrated Catalog 
Administration: Access Method Services Reference . 
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Using the Services Of Data-in- Virtual 



Each invocation of the DIV macro requests any one of eight distinct services provided by 
data-in-virtual: 



IDENTIFY 

ACCESS 

MAP 

SAVE 

RESET 

UNMAP 

UNACCESS 

UNIDENTIFY 



Identify 



Access 



To request processing of a data-in-virtual object, an application must invoke the IDENTIFY 
service. The application uses IDENTIFY to tell the system which data-in-virtual object it wants 
to process, via the DDNAME parameter. IDENTIFY generates a unique id, or token, that 
uniquely represents the application's individual request to use the given data set. It returns this 
id to the application. When the application requests other kinds of services with the DIV 
macro, it supplies this id as an input parameter. 
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To access the object, an application must use the ACCESS service. ACCESS is similar to the 
OPEN macro of VSAM. It has a mode parameter of READ or UPDATE, and it gives your 
application the right to read or update the object. ACCESS excludes other applications from 
reading and updating the object, as determined by the current SHAREOPTIONS definition for 
the object. You normally invoke ACCESS after you invoke IDENTIFY and before you invoke 
MAP. 



Map 



W 

•0 



The data object is stored in units of 4096-byte blocks. An application uses the MAP service to 
specify the part of the object that is to be processed in virtual storage. It can specify the entire 
object (all of the blocks), or a part of the object (any continuous range of blocks). 

After ACCESS, the application issues a GETMAIN macro to obtain a virtual storage area 
large enough to contain the string of blocks that is to be processed. The size of the object, 
which is returned (optionally) by ACCESS, can determine how much virtual storage needs to be 
requested when the application issues GETMAIN. After GETMAIN, the application invokes 
MAP. MAP establishes a direct correspondence between blocks on the object and pages in 
virtual storage. A continuous range of pages corresponds to a continuous range of blocks. This 
correspondence is called a virtual storage window, or a window. 

After MAP, the application can look into the virtual storage area that is framed by the window. 
When it looks into this virtual storage area, it sees the same data that is on the object. When 
the application references this virtual storage area, it is referencing the data from the object, 
which is available in the window whenever a reference is made inside the window. To reference 
the area in the window, the application simply uses any conventional processor instructions that 
access memory. 
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Although the object data becomes available in the window when MAP is used, no actual 
movement of data from the object into the window occurs at that time. Actual movement of 
data from the object to the window can only occur when the application refers to data in the 
window. When a page in the window is referenced for the first time, a page fault occurs. When 
the page fault occurs, the system reads the permanent storage block into real storage. 

When data is read into real storage, the data movement involves only the precise block that is 
referenced, which replaces the corresponding page in the window. Thus, only the blocks that are 
referenced by an application are ever read into real storage. 

Notes: 

1. If the application would rather keep in the window the data that existed before the window 
was established (instead of having the object data appear in the window) , it can specify this by 
using the RETAIN parameter. This would be useful when creating an object or overlaying the 
contents of an object. 

2. An important concept for data-in-virtual is the concept of freshly obtained storage. When 
virtual storage has been obtained by a GETMAIN macro and not subsequently modified, the 
storage is considered to be in the freshly obtained state. When referring to this storage or any 
of its included pages, this book uses the terms, "freshly obtained storage" and "freshly 
obtained pages." If a program stores into a freshly obtained page , only that page loses its 
freshly obtained status, while other pages still retain it. 



Save and Reset 



Unmap 



After the MAP service, the application can access the data inside the window directly through 
normal programming techniques. When the application changes some data in the window, 
however, the data on the object does not consequently change. If the application wants the data 
changes in the window to appear in the object, it must use the SAVE service. SAVE causes all 
changed blocks inside the window to be written out to the object. Unchanged blocks are not 
written. When SAVE completes, the object contains any changes that the application made 
inside the virtual storage window. If a SAVE is preceded by another SAVE, the second SAVE 
will only pick up the changes that occurred since the previous SAVE. 

If the application changes some data in a virtual storage window but then decides not to keep 
those changes, it can use the RESET service to remove the changes from the window. 



When the application is finished processing the part of the object that is in the window, it 
eliminates the window by using UNMAP. To process a different part of the object, one not 
already mapped, the application can use the MAP service again. Because parts of the same 
object can be viewed simultaneously through several different windows, the application can set 
up separate windows on the same object. However, a specific page of virtual storage cannot be 
in more than one window at a time. The SAVE, RESET, MAP, and UNMAP services can be 
invoked repeatedly as required by the processing requirements of the application. 



i 
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Unaccess 



Unidentify 



If the application has temporarily finished processing the object but still has other processing to 
perform, it uses UNACCESS to relinquish access to the object. Then, other programs can 
access the object. If the application needs to access the same object again, it can regain access 
to the object by using the ACCESS service again without having to use the IDENTIFY service 
again. 



The application uses UNIDENTIFY to revoke its previous request, which was made by 
IDENTIFY, to process a data-in-virtual object. 



I 
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The IDENTIFY Service 



Your program uses IDENTIFY to select the data-in-virtual object that you want to process. 
IDENTIFY has three parameters: ID, DDNAME and TYPE. 

Parameters of IDENTIFY - DDNAME: When you specify the IDENTIFY service, you specify 
a DDNAME parameter that identifies your data-in-virtual object. IDENTIFY causes the 
system to create a unique eight-byte id that it returns to you, stored in the address that you 
specify with the ID parameter. Your program supplies this id as a token input parameter on 
subsequent invocations of other data-in-virtual services. 

Simultaneous requests for different processing activities against the same data-in-virtual object 
can originate from different tasks or from different routines within the same task. Each task or 
routine requesting processing activity against the data set must invoke the identify service. To 
correlate the various DIV macro invocations and processing activities, the eight-byte ids 
generated by IDENTIFY are sufficiently unique to reflect the individuality of the IDENTIFY 
request, yet they all reflect the same data-in-virtual object. 

Parameters of IDENTIFY - TYPE: The TYPE parameter indicates the storage format of the 
data set name. You must specify TYPE = DA to indicate that the data set name is found in a 
data definition statement. 



The ACCESS Service 



Your program uses the ACCESS service to request permission to read or update the object. 1 

ACCESS uses three parameters: ID, MODE, and SIZE. ^ 

Parameters of ACCESS - ID: When you issue a DIV macro that requests the ACCESS service, 
you must also specify, on the ID parameter, the identifier that the IDENTIFY service returned. 
The ID parameter tells the system what object you want access to. When you request 
permission to access the object under a specified ID, the system checks the following conditions 
before it grants the access: 

• The ID specified with your ACCESS request has already been established by a previous 
invocation of IDENTIFY. 

• You have not already accessed the object under the same unique eight-byte ID. Before 
you can reaccess an already-accessed object under the same ID, you must first invoke 
UNACCESS for that ID. 

• If your installation uses RACF, you must have the proper RACF authorization to access 
the object. 

• If you are requesting read access, the object must not be empty. You use the MODE 
parameter to request read or update access. 



( 
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Parameters of ACCESS - MODE: Multiple users (using different IDs) can request access to 
the same object. If you expect multiple users, VSAM serializes their access if you specify 
SHAREOPTIONS(l,3) in the DEFINE CLUSTER access method service request when you 
create the data set. If you specify other than SHAREOPTIONS(l,3), VSAM does not perform 
serialization that is suitable for data-in-virtual usage, and the responsibility for data set 
serialization rests with you. 

When your JCL specifies SHAREOPTIONS(l,3) and a disposition of SHR, the MODE 
parameter determines how your program accesses the object. You can specify a mode parameter 
of READ or UPDATE. READ lets your program share read access to the object with any 
other programs that have requested read access under separate IDs. READ does not let you 
invoke SAVE, which changes the object. However, it does not prevent you from making 
changes in the window. 

UPDATE lets you invoke SAVE to change the data in the object, and it prevents other 
programs from accessing the object. When you request UPDATE, no one else can use the data 
set in either read or update mode. Conversely, when another program is accessing the object in 
update mode, it is impossible for you to read the object or update it. 

Parameters of ACCESS - SIZE: SIZE specifies the address of a four-byte field. When control 
is returned to your program after the ACCESS service executes, the four-byte field contains the 
current size of the object. The size is the number of blocks that must be mapped to ensure that 
the entire object is mapped. If SIZE is omitted or if SIZE = * is specified, the size is not 
returned. 



The MAP Service 



The MAP service is used to make an association between part or all of a data object, the 
portion being specified by the OFFSET and SPAN parameters, and your program's virtual 
storage. This association, which is called a virtual storage window, takes the form of a 
one-to-one correspondence between specified blocks on the object and specified pages in the 
virtual storage. After the MAP is complete, your program can then proceed with the processing 
of the data in the window. The RETAIN parameter specifies whether data that is currently in 
the window is to be retained or to be replaced by the data from the associated object. 

Note: Virtual storage pages that are page-fixed cannot be mapped into a virtual storage 
window. Once the window exists, you can page-fix data inside the window so long as it is not 
fixed when you issue SAVE or UNMAP. 

The DIV macro has five parameters which are used when invoking MAP: ID, OFFSET, 
SPAN, AREA, and RETAIN. 

Parameters of MAP - ID: The ID parameter specifies the storage location containing the 
unique eight-byte value that was returned by IDENTIFY. The map service uses this value to 
determine which object is being mapped under which request. 

If you specify the same ID on multiple invocations of the MAP service, you can create 
simultaneous windows corresponding to different parts of the object. However, an object block 
that is mapped into one window cannot be mapped into any other window created under the 
same ID. If you use different IDs, however, an object block can be included simultaneously in 
several windows. 
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Parameters of MAP - OFFSET and SPAN: The OFFSET and SPAN parameters indicate a 

range of blocks on the object. Blocks in this range appear in the window. OFFSET indicates 

the first object block in the range, while SPAN indicates how many contiguous blocks make up | 

the range. An offset of zero indicates the beginning of the object. For example, an offset of zero 

and a span of ten causes the block at the beginning of the object to appear in the window, 

together with the next nine object blocks. The window would then be ten pages long. 

Specifying OFFSET = * or omitting OFFSET causes a default OFFSET of zero to be used. 
Specifying SPAN = 0, SPAN = * or omitting SPAN results in a default SPAN of the number of 
blocks needed to MAP the entire object, starting from the block indicated by OFFSET. 
Specifying both OFFSET = * and SPAN = * or omitting both causes the entire object to appear 
in the window. 

The OFFSET and SPAN parameters may be used to specify a range spanning any portion of 
the object, the entire object, or extending beyond the object. Specifying a range beyond the 
object enables a program to add data to the object, causing the object to grow. If data in a 
mapped range beyond the object is saved (using the SAVE service), the size of the object is 
updated to reflect the new size. 

To use the OFFSET parameter, specify the storage location containing the block offset of the 
first block to be mapped. The offset of the first block in the data object is zero. To use the 
SPAN parameter, specify the storage location containing the number of blocks in the mapped 
range. 

Parameters of MAP - AREA: When you specify MAP, you must also specify an AREA 

parameter. AREA indicates the beginning of a virtual storage space large enough to contain 

the entire window. Before invoking MAP, you must ensure that this virtual storage space is j 

owned by your task. This can be ensured by specifying a storage area that is obtained by the i| 

GETMAIN macro. The storage must belong to a single, pageable private area subpool. It must 

begin on a 4096-byte boundary (that is, a page boundary) and have a length that is a multiple 

of 4096 bytes. 

Note that any virtual storage space assigned to one window cannot be simultaneously assigned 
to another window. If your MAP request specifies, via the AREA parameter, a virtual storage 
location that is part of another window, the request is rejected. 

A virtual storage area that is mapped into a window cannot be freed as long as the map exists. 
Attempts to do this will result in the virtual space being made unusable and an ABEND of the 
program. Subsequent attempts to reference the mapped virtual space will also result in an 
ABEND. 

Parameters of MAP - RETAIN: The RETAIN parameter determines what data is to be viewed 
in the window. It can be either the contents of the virtual storage area (that corresponds to the 
window) the way it was before you invoked MAP, or it can be the contents of the object. 

If you specify RETAIN = NO, or do not specify the RETAIN parameter at all (which defaults 
to RETAIN = NO), then the contents of the object replaces the contents of the virtual storage 
whenever a page in the window is referenced. Virtual storage that corresponds to a range 
beyond the end of the object appears as binary zeros when referenced. RETAIN = NO can be 
used when you want to view data already on the object, possibly with the intent of changing 
some data and saving it back to the object. 

If you specify RETAIN = YES, then the window retains the contents of virtual storage. The ■ 

data in the window are not replaced by data from the object as a result of the MAP operation. ^ 
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If you issue a subsequent SAVE, the data on the object is REPLACED by the data in the 
window. If the window extends beyond the object and your program has not referenced the 
pages in the extending part of the window, then the extending pages are not saved. However, if 
the extending pages have been referenced, then they are saved on the object, causing the object 
to be extended so it can hold the additional data. 

RETAIN = YES can also be used to reduce the size of (truncate) the object. If the part you 
want to truncate is mapped with RETAIN = YES and the window consists of freshly obtained 
storage, then at SAVE time, the data object size is reduced. 

If you want to have zeroes written at the end of the object, then the corresponding virtual 
storage must be explicitly set to zero prior to the SAVE. 



The SAVE Service 



The SAVE service causes data to be written from virtual storage onto the data-in-virtual object. 
When you invoke SAVE, you specify a single and continuous range of blocks on the 
data-in-virtual object. Any virtual storage windows inside this range are eligible to participate 
in the SAVE. 

For a SAVE request to be valid, the object must currently be accessed with 
MODE = UPDATE, under the same ID as the one specified on this SAVE request. Because an 
object can be mapped beyond its current end, the object might be extended when the SAVE is 
done if there are changed pages beyond the current end at the time of the ACCESS. On the 
other hand, the SAVE truncates the object if freshly obtained pages are mapped in a range that 
extends to or beyond the end of the object. In either case, the new object size is returned to 
your program if you specify the SIZE parameter. 

Pages within the range cannot be page fixed when the SAVE is issued. Mapped pages in the 
range that are freshly obtained are written as binary zeroes if they occur before a changed page. 
The DIV macro has four parameters which are used when invoking SAVE: ID, OFFSET, 
SPAN and SIZE. 

Notes: 

1. If data to be saved has not changed since the last SAVE, no I/O will be performed. The 
performance advantages of using data-in-virtual are primarily because of the automatic 
elimination of unnecessary read and write I/O operations. 

2. The range specified with SA VE refers to the blocks of the object, which relate to pages inside 
a window. 

3. The range specified with SA VE can extend beyond the end of the object. 

4. Pages of the object not mapped to any window are not saved. 

5. Pages in a window that lie outside the specified range are not saved. 

Parameters of SA VE - ID: The ID parameter tells the SAVE service which data object is being 
written to under which request. Use ID to specify the storage location containing the unique 
eight-byte name that was returned by IDENTIFY. The object must have been previously 
accessed with MODE = UPDATE under the same ID as the one specified for SAVE. 
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Parameters of SA VE - OFFSET and SPAN: The OFFSET and SPAN parameters are used to 
select a continuous range of object blocks, within which the SAVE service can operate. 
OFFSET indicates the first block and SPAN indicates the number of blocks in the range. As in 
the MAP service, the offset and span parameters refer to object blocks; they do not refer to 
pages in the window. 

Specifying OFFSET = * or omitting OFFSET causes the default offset (zero) to be used. The 
zero offset does not omit or skip over any of the object blocks, and it causes the range to start 
right at the beginning of the object. Specifying SPAN = 0, SPAN = *, or omitting SPAN gives 
you the default span. The default span includes the first object block after the part skipped by 
the offset, and it includes the entire succession of object blocks up to and including the object 
block that corresponds to the last page of the last window. 

When SAVE executes, it examines each virtual storage window established for the object. In 
each window, it detects every page that corresponds to an object block in the selected range. 
Then, if the page has changed since the last SAVE, the page is written on the object. (If the 
page has not changed since the last SAVE, it is already identical to the corresponding object 
block and there is no need for it to be saved.) Although SAVE discriminates between blocks on 
the basis of whether they have changed, it has the effect of saving all window pages that lie in 
the selected range. Specifying both OFFSET = * and SPAN = * or omitting both causes the 
system to save all changed pages in the window without exceptions. 

To use the OFFSET parameter, specify the storage location containing the block offset of the 
first block to be saved. The Offset of the first block in the object is zero. To use the SPAN 
parameter, specify the storage location containing the number of blocks in the range to be 
saved. 

Parameters of SA VE - SIZE: Invoking SAVE can change the size of the object. When you 
specify SIZE, the size of the object after SAVE completes is returned in the virtual storage 
location specified by the SIZE parameter. If you omit SIZE or specify SIZE = *, the size value 
is not returned. 



Effect of RETAIN Mode on SAVE 



While RETAIN cannot be specified on SAVE, the RETAIN mode of each included window 
affects how the window is saved. 

When RETAIN = NO was specified for a previously mapped window, all pages in the virtual 
storage window appear to contain the contents of the object and are considered unchanged with 
respect to the object. When SAVE is issued, only pages in mapped windows that are changed 
and correspond to blocks within the range being saved are written to the object. Pages that 
might have been freshly obtained before the MAP, but have not been referenced since the 
MAP, still are not saved because they appear to contain the data that is on the corresponding 
blocks of the object. As with RETAIN = YES, the size of the object can still increase if the 
saved range extends beyond the current end of the object and it contains mapped windows with 
changed pages. 

When RETAIN = YES was specified for a mapped virtual storage window, all pages in the 
window that are not freshly obtained are considered changed. SAVE writes all these pages, 
which are considered changed, onto the object. If both the range to be saved and the previously 
mapped virtual storage window ranges extend beyond the current end of the object, 



i 
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then the object is extended to hold the additional data. In addition, freshly obtained pages in 
the window will be written to the object as zeroes if: 

• The freshly obtained pages correspond to blocks on the object within the current object 
size. 

• The freshly obtained page currently being saved is followed, in the current window or in 
another window, by one or more changed pages. 

On the other hand, freshly obtained pages in the window will cause the object to shrink in 
size (i.e. to be truncated) if: 

• The freshly obtained page or pages are at the end of the window; that is, there are no 
changed pages beyond the last unchanged page. 

• No other mapped windows beyond the current window contain changed pages. 

• At least one of the freshly obtained pages in the window corresponds to the last block on 
the object; that is, the end of the object is mapped to a freshly obtained page. In this 
situation, the last block of the window must be equal to or greater than the last block of 
the object. 

If all of the listed conditions for truncation are true, then the object is truncated to the last 
block that still contains data, either because (1) it corresponded to the last changed page in a 
mapped window or because (2) there was no mapped window page corresponding to that block. 
In the second case, the block is not affected by the SAVE; it contains the data that existed 
before the SAVE. 



) 



The RESET Service 



At times during program processing, your program might have made changes to pages in the 
virtual storage window, and might no longer want to keep those changes. RESET, which is the 
opposite of SAVE, causes data from the object to appear in the virtual storage window. As 
with SAVE and MAP, the range to be reset refers to the object rather than the virtual storage. 
RESET only resets windows that are within the specified range, and it resets all the windows in 
the range. 



Effect of RETAIN mode on RESET 



Although the RETAIN parameter cannot be specified when you invoke RESET against a 
virtual storage window, the system remembers how RETAIN was specified on the MAP 
operation that created the window. Therefore, when you invoke RESET, the system resets the 
window one way for RETAIN = NO and another way for RETAIN = YES: 

• If the window was created with RETAIN = NO, then after the RESET the data in the 
window is the same as the object data, as of the last SAVE. This applies to all the pages in 
the window. 



) 



If the window was created with RETAIN = YES, then after the RESET the pages in the 
window acquire a freshly obtained status unless you have been doing SAVE operations on 
this window. Individual object blocks changed by those SAVE operations re-appear after 
the RESET in their corresponding window pages, together with the other pages. However, 
the other pages appear freshly obtained. 
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Note: Regardless of the RETAIN mode of the window, any window page that corresponds to 
a block beyond the end of the object will appear as a freshly obtained page. 

I 

Parameters of RESET - ID: The ID parameter tells the RESET service what data object is 
being written to. Use ID to specify the storage location containing the unique eight-byte name 
that was returned by IDENTIFY and used with previous MAP requests. The object must be 
previously accessed (with either MODE = READ or MODE = UPDATE) under the same ID as 
the one being specified for RESET. 

Parameters of RESET - OFFSET and SPAN: The OFFSET and SPAN keywords are used to 
indicate the RESET range, the part of the object that is to supply the data for the RESET. As 
with MAP and SAVE, OFFSET indicates the first object block in the range, while SPAN 
indicates how many contiguous blocks make up the range, starting from the block indicated by 
OFFSET. The first block of the object has an offset of zero. 

To use OFFSET, specify the storage location containing the block offset of the first block to be 
reset. To use SPAN, specify the storage location containing the number of blocks in the range 
to be RESET. Specifying OFFSET = * or omitting OFFSET causes a default OFFSET of zero 
to be used. Specifying SPAN = * or omitting SPAN sets the default to the number of blocks 
needed to reset all the virtual storage windows that are mapped under the specified ID, 
however, starting only with the block number indicated by OFFSET. Specifying both 
OFFSET = * and SPAN = * or omitting both resets all windows that are currently mapped 
under the specified ID. 

The UNMAP Service 

I 

Your program uses the UNMAP service to remove the association between a window in virtual 
storage and the object. Each UNMAP request must correspond to a previous MAP request. 
Note that, because UNMAP has no effect on the object, changes made in virtual storage but 
not yet saved are not saved on the object when UNMAP is issued. UNMAP has three 
parameters: ID, AREA, and RETAIN. 

Parameters of UNMAP - ID: The ID parameter that you specify is the address of an 
eight-byte field in storage. That field contains the identifier associated with the object. The 
identifier is the same value that the IDENTIFY service returned, which is also the same value 
you specified when you issued the corresponding MAP request. 

Parameters of UNMAP - AREA: The AREA parameter specifies the address of a four-byte 
field in storage that contains a pointer to the start of the virtual storage to be unmapped. 
This address must point to the beginning of a window. It is the same address that you 
provided when you issued the corresponding MAP request. 

Parameters of UNMAP - RETAIN: RETAIN specifies the state that virtual storage is to be 
left in after it is unmapped; that is, after the correspondence between virtual storage and the 
object is removed. 

Provided that you specify RETAIN = NO for the MAP service, specifying RETAIN = YES on 

the corresponding UNMAP transfers the value of the object into the window. In this case, 

RETAIN = YES with UNMAP specifies that the virtual storage area corresponding to the 

unmapped window is to contain the same data as the object. After UNMAP, your program 

can still reference and change the data in this virtual storage but can no longer save it on the ■ 

object unless the virtual area is mapped again. ^ 
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Specifying RETAIN = NO with UNMAP indicates that the data in the unmapped window is to 
be freshly obtained. 

Notes: 

1. If RETAIN = YES is specified on MAP, RETAIN = YES on the corresponding UNMAP does 
not transfer the object value into the window. In this case, UNMAP leaves the window 
contents unchanged. 

2. If UNMAP is issued with RETAIN = NO, and there are unsaved changes in the virtual storage 
window area, those changes are lost. 

3. Ifunmap is issued with RETAIN = YES, and there are unsaved changes in thge window, they 
remain in the virtual storage. 

4. The RETAIN parameter of MAP and UNMAP can be used to move data on the object 
without having to physically move it in virtual storage. For example, if you map block 2 to an 
area of virtual storage specifying RETAIN = NO, then block 2 of the object appears in the 
virtual storage window. If you then issue UNMAP with RETAIN= YES, block 2 is retained 
in virtual storage, even though the correspondence with the object has been removed. 

Then, by mapping the virtual area to block 7 and specifying RETAIN= YES, you set up a 
correspondence between the same virtual area and block 7, with the original data from block 2 
retained in the window. Finally, by issuing SAVE, you save the window (containing the block 
2 data) on block 7 of the object. For more information on RETAIN, see the MAP and SA VE 
services. Note that the second map need not be for the same data object. 

5. Unmapping with RETAIN '— YES has certain performance implications. It causes 
unreferenced pages, and maybe some unchanged ones, to be read from the object. 



The UNACCESS and UNIDENTIFY Services 

You use UNACCESS to terminate your access to the object for the specified ID. UNACCESS 
automatically includes an implied UNMAP. If you issue an UNACCESS with outstanding 
virtual storage windows, any windows that exist for the specified ID are unmapped with 
RETAIN = NO. The ID parameter is the sole parameter of the UNACCESS service, and it 
designates the same ID that you specified in the corresponding ACCESS. As in the other 
services, use ID to specify the storage location containing the unique eight-byte name that was 
returned by IDENTIFY. 

You use UNIDENTIFY to notify the system that your use of an object under the specified ID 
has ended. If the object is still accessed as an object under this ID, UNIDENTIFY 
automatically includes an implied UNACCESS. The UNACCESS, in turn, issues any necessary 
UNMAPs, using RETAIN = NO. The ID parameter is the only parameter for UNIDENTIFY, 
and it must designate the same ID as the one specified in the corresponding ACCESS. As in the 
other services, use ID to specify the storage location containing the unique eight-byte name that 
was returned by IDENTIFY. 



I^jpr 
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Conditions for Invocation of Data-in-Virtual 

The services of data-in-virtual execute synchronously, i.e. control is not returned from the DIV 
macro until the service is completed. Thus, before you can successfully invoke a service, the 
previous service must be complete. However, multiple services can be executing concurrently for 
different IDs. To invoke the DIV macro, you can be in the supervisor state, or you can be in 
the problem program state with a user key. You must supply a standard 72 byte save area. To 
issue the DIV macro, you must be: 

1 . enabled for I/O and external interrupts. 

2. executing in 31 bit addressing mode. 

3. executing in an environment that allows the use of SVCs. This means that you must be: 

• in task (TCB) mode. 

• not holding any locks. 

• in non-cross memory mode. 

Sharing Services within a Task 

The services of data-in- virtual are task-oriented. When a user issues IDENTIFY, an association 
is established between the ID assigned and the user's task. The type of association differs, 
however, depending on whether the task is authorized or not. The authorized task runs in 
supervisor state, has a system key (0-7), or has APF authorization. The non-authorized task 
runs in problem program state, with a user key, and with no APF authorization. 

• For the non-authorized user, the use of data-in- virtual services for a specific ID is strictly 
local to its immediate task. That is, all services for a particular ID must be requested by the 
same task that requested IDENTIFY, and obtained the ID. 

• For the authorized user, one task can issue IDENTIFY while authorized subtasks of that 
task, using the ID returned by IDENTIFY, can request all the other services, except 
ACCESS. 

However, any task, authorized or not, may reference or change the data in a mapped virtual 
storage window, even if the window was mapped by another task, and even if the object was 
identified and accessed by another task. As long as the task can address the window, it is 
allowed to reference or change the included data. 

Because data-in-virtual services affect virtual storage, the storage protect key of any task that 
requests a service (under a given ID) must be the same as the storage protect key of the task 
that issued the IDENTIFY (that obtained the ID). This is not required if the task has storage 
protect key zero. 

Miscellaneous Restrictions 

• When you attach a new task, you cannot pass ownership of a mapped virtual storage 
window to the new task. That is, the ATTACH keywords GSPV and GSPL cannot be used 
to pass the mapped virtual storage. Ownership of subpool zero cannot be passed using 
GSPV and GSPL keywords. 



< 
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• Data-in-virtual services cannot be invoked in cross memory mode. There are no 

restrictions, however, against referencing and updating a mapped virtual storage window in 
cross memory mode. 

Return Codes, Reason Codes and Abend Codes. 

If control is returned to the user after the DIV macro executes, a return code is supplied in the 
low order (rightmost) byte of general register 15. Successful completion is indicated by a zero 
return code and unsuccessful completion is indicated by a non-zero return code. When control 
is returned after an unsuccessful completion, a reason code is supplied in the two low order 
bytes of general register zero. 

If control is not returned, an abend code and a reason code are supplied. The hexadecimal 
values of the reason, return and abend codes are: 



1 







Reason 
code 

none 
0001 
0002 
0003 
0004 

0005 

0006 
0007 
0008 
0009 

000A 

000B 
000C 

000D 

000E 

000F 

0010 
0011 
0012 

0013 

0014 

0015 

0016 



Return 
code 

00 

none 

none 

none 

none 

none 

none 
none 
none 
none 

08 

none 
none 

none 

none 

none 

none 
none 
none 

none 

none 

none 



Abend 
code 

none 

08B 

08B 

08B 

08B 

08B 

08B 
08B 
08B 
08B 

none 

08B 
08B 

08B 

08B 

08B 

08B 
08B 
08B 

08B 

08B 

08B 

08B 



0017 


OC 


none 


0018 


none 


08B 


0019 


none 


08B 


001 A 


04 


none 


001B 


none 


08B 


001C 


08 


none 


00 ID 


none 


08B 


001E 


none 


08B 


001F 


none 


08B 



Explanation 



Successful completion. 

Unknown service was requested. 

Unknown parameter list format. 

Input parameter list cannot be addressed. 

Storage specified in the parameter list cannot be 

addressed. 

The parameter list contains a reserved field that 

does not contain binary zeroes. 

The caller is not running in task mode. 

The caller is in cross memory mode. 

An invalid TYPE is specified. 

The supplied ID is not a valid ID or is an ID that 

cannot be used by the caller. 

There is another service currently executing with 

the specified ID. 

The object is already accessed with the specified ID. 

The caller does not have proper RACF 

authorization to the requested object. 

The requested window exceeds the maximum 

allowable size for the object. 

The object is not currently accessed for the specified 

ID. 

The specified range overlaps a range that is already 

mapped for the specified ID. 

The specified range overlaps another mapped range. 

Undetermined user error. 

The virtual storage specified does not begin on a 

4K boundary. 

The virtual storage specified is not in a pageable 

private area subpool. 

The virtual range specified cannot be used to map 

an object. 

The virtual range specified contains at least one 

page that was not obtained by a GETMAIN 

macro, and RETAIN = NO was not specified. 

The virtual range specified contains at least one 

fixed page. 

An I/O error has occurred. 

Caller does not have UPDATE access to the object. 

A page to be saved or reset was in the page fixed 

state. 

The specified range does not encompass any 

mapped area of the object. 

The virtual storage area specified to be unmapped 

is not currently mapped. 

The object cannot be accessed at the current time. 

The accessed object is not at the correct Control 

Interval size. 

The length of the ddname exceeds the maximum 

size allowed. 

The caller's storage protect key is not the same as 

when IDENTIFY was invoked. 
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Reason 
code 

0020 

0021 

0022 

0023 

0024 
0025 

0026 

0027 

0028 

0801 



0802 
0803 

0804 
0805 
0806 
0807 



0808 



Abend 
code 



Explanation 



Return 
code 

none 08B An ACCESS was attempted by a task that does not 

own the specified ID. 
0C none Portions of the object could not be retained in 

virtual storage as requested, 
none 08B The specified storage to be mapped is not owned by 

the task chain that did the IDENTIFY, 
none 08B Part or all of the specified storage to be mapped is 

not in the user's key. 
none 08B The caller holds the local lock, 

none 08B The caller is executing in an environment that 

precludes the use of SVCs. 
none 08B The caller is not executing in 31 bit addressing 

mode, 
none 08B The specified offset and span describe a range that 

goes beyond the maximum supported object size, 
none 08B The caller has attempted to access an empty object 

for reading. 
08 none System error - Insufficient storage available to build 

the necessary data-in-virtual control block 

structure. 
08 none System error - I/O driver failure. 

0C none System error - A necessary page table could not be 

read into real storage. 
0C none System error - Catalog update failed, 

none 08B Unexpected system error 

0C none System error - I/O error. 

04 none Media damage may be present in allocated DASD 

space. The damage is beyond the currently saved 

portion of the object. The SAVE completed 

successfully. 
08 none System error - I/O from a previous request has not 

completed. 
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DIV Macro Programming Examples 



The following programming examples illustrate how to code and execute a program that 
processes a data-in-virtual object. 



Executing an Application 



The following JCL job causes the execution of an application program called SAMPLE. The 
function of SAMPLE is to perform some kind of application-oriented processing on the 
data-in- virtual object, DIV. SAMPLE, that was allocated in the previous example. 

When SAMPLE executes, it issues a DIV macro specifying to the IDENTIFY service the name 
of the data-in-virtual object that it will process. To identify the data set, SAMPLE specifies the 
ddname, DYNAMIC, on the DDNAME parameter of the DIV macro. 

The system then connects the actual data set name, DIV. SAMPLE, with the program that 
will process it. The link between the application program and the data set is the name, 
DYNAMIC, which appears in both the application and the JCL. 



) 



//* 




//* 




//* 


EXECUTE A DATA- IN- VIRTUAL APPLICATION 


//* 




//SAMPLE 


EXEC PGM=SAMPLE 


//STEPLIB 


DD DSN=DIV22.LOAD. JOBS ,DISP=SHR 


//DYNAMIC 


DD DSN=DIV. SAMPLE, DISP=SHR 


//SYSABEND 


DD SYSOUT=* 


/* 





) 
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Processing a Data-in- Virtual Object. 

The following example shows a program that processes a data-in-virtual object. The first part of 
the program identifies the data set and accesses the object. Then it obtains the virtual storage 
where it will place the window. 



SAMPLE 

SAMPLE 

SAMPLE 
* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

@MAINENT DS 

USING 

B 

DC 

DC 

DROP 

STM 

LR 



@PROLOG 



CSECT , 
AMODE 31 
RMODE ANY 

FUNCTION: GETMAIN SOME VIRTUAL STORAGE. THEN 
IDENTIFY AND ACCESS THE LINEAR DATA SET. THEN 
MAP AND PROCESS THE VIRTUAL STORAGE, AND STORE 
DATA INTO IT. THEN DO SOME SAVES AND RESETS. 
FINISH UP WITH Atf UNMAP , AN UNACCESS AND AN 
UNIDENTIFY. ALL INVOCATIONS OF DATA- IN- VIRTUAL 
IN THIS PROGRAM WILL DEFAULT TO • RETAIN = NO ' . 

DESCRIPTION: THIS JOB MAKES CHANGES IN THE 
LINEAR DATASET CLUSTER, ' DIV. SAMPLE ' , WHICH IS 
TREATED AS A LINEAR DATASET. AFTER THIS JOB 
IS RUN, THE DATASET WILL CONTAIN SEVEN PAGES 
OF ONES, FOLLOWED BY ONE PAGE OF ZEROES, 
FOLLOWED BY EIGHT PAGES OF FIVES. IT IS 
ASSUMED THE DATASET WAS CREATED BY A DEFINE 
CLUSTER COMMAND AND THAT IT CONTAINS ZEROES 
WHEN THIS PROGRAM BEGINS TO EXECUTE. 



OH 

*,R15 

©PROLOG 

AL1(14) 

C SAMPLE PROGRAM 1 

R15 

R14,R12,12(R13) 

R12,R15 



STD ENTRY LINKAGE 



USING SAMPLE, R12 

ST R13 , SAVEAREA+4 

LR R2,R13 

LA R 13, SAVE ARE A 

ST R13,8(R2) 

SR R15,R15 



CLEAR R15 



GET STORAGE FOR THE WINDOW 

GETMAIN RU,LV=16*4096,SP=0,BNDRY=PAGE 
ST R1,MAPPTR1 PTR TO STORAGE 

INVOKE IDENTIFY SERVICE OF DIV MACRO 

DIV IDENTIFY , DDNAME=DDNAME , TYPE=DA , ID=TESTID 
LTR R15,R15 CHECK IF RC IS ZERO 

BNZ ERROR IDENTIFY FAILED 

INVOKE ACCESS SERVICE OF DIV MACRO 

DIV ACCESS , MODE=UPDATE , ID=TESTID 

LTR R15,R15 CHECK IF RC IS ZERO 

BNZ ERROR ACCESS FAILED 



( 
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Processing a Data-in- Virtual Object (continued) 

The program maps the object. The resulting virtual storage window is eight pages long, and it 
corresponds to the second eight blocks of the object. The window is situated in the virtual 
storage obtained earlier by the GETMAIN macro. The program fills the window with fives, 
then saves the window back into the second eight blocks of the object. The program eradicates 
the window by invoking UNMAP. 



f 



* 


INVOKE THE MAP SERVICE OF THE DIV MACRO 




* 
* 


TO SKIP THE FIRST EIGHT BLOCKS OF THE OBJECT 






L 


R3, EIGHT GET SPAN 






ST 


R3,SPVALUE INITIALIZE SPAN 






ST 


R3,OFFS ' INITIALIZE OFFSET 






DIV 


MAP , ID=TESTID , AREA=MAPPTR1 , 
SPAN=SPVALUE , OFFSET=OFFS 


X 




LTR 


R15,R15 CHECK IF RC IS ZERO 




* 


BNZ 


ERROR MAP FAILED 




* 

* 


FILL 


IN 5'S FOR ALL EIGHT MAPPED BLOCKS 






L 


R1,MAPPTR1 POINTS TO WINDOW 






LR 


R2,R1 POINTS TO MAP 






SR 


R5,R5 COUNTER 32 KBYTES 






L 


R6,PAGE8 COUNTER MAXIMUM 






IC 


R3,N55 5S USED AS FILLER 




LOOP1 


STC 


R3 , ( , R2 ) STORE INTO MAP 






LA 


R2,1(,R2) POINTS NEXT BYTE 






LA 


R5,1(,R5) COUNT UP ONE BYTE 






CR 


R5,R6 LAST BYTE OF MAP? 




* 


BM 


LOOP1 DO AGAIN IF NOT 




* 
* 


INVOKE THE SAVE SERVICE OF THE DIV MACRO 






DIV 


SAVE , ID=TESTID , SIZE=OB JSIZE 






LTR 


R15,R15 CHECK ZERO RC 




* 


BNZ 


ERROR SAVE FAILED 




* 
* 


INVOKE THE UNMAP SERVICE OF THE DIV MACRO 






DIV 


UNMAP , ID=TESTID , AREA=MAPPTR1 






LTR 


R15,R15 CHECK ZERO RC 




* 


BNZ 


ERROR UNMAP FAILED 




* 
* 


OBJECT NOW HAS 8 CONTIGUOUS PAGES OF 5 ' S 
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Processing a Data-in-Virtual Object (continued) 

The program creates a new window that includes the first eight blocks of the object. This map 
omits OFFSET, causing a default offset of zero to be used with the specified span of eight 
blocks. After filling the window with ones, the program invokes RESET against the eighth 
block of the object, which corresponds to the eighth page of the window. Because the 
information provided by the reset comes from the object, which still contains zeroes, the eighth 
page in the window is set to zeroes. 



* 


INVOKE MAP SERVICE FOR 


FIRST EIGHT 4K 




* 
* 


BLOCKS OF DATASET, WITH 


DEFAULT OFFSET. 






L 


R3, EIGHT 


GET VALUE OF SPAN 






ST 


R3,SP VALUE 


INITIALIZE SPAN 






DIV 


MAP , ID=TESTID , AREA=MAPPTR1 , 


X 






SPAN=SPVALUE 








LTR 


R15,R15 


CHECK ZERO RC 




* 


BNZ 


ERROR 


MAP FAILED 




* 
* 


FILL 


IN DATA - l'S FOR 


THE FIRST 8 PAGES 






L 


R1,MAPPTR1 


POINTS TO WINDOW 






LR 


R2,R1 


POINTS TO MAP 






SR 


R5,R5 


COUNTER 32 KBYTES 






L 


R6,PAGE8 


COUNTER MAXIMUM 






IC 


R3,N11 


IS USED AS FILLER 




LOOP 2 


STC 


R3,0( ,R2) 


STORE INTO MAP 






LA 


R2,l( ,R2) 


POINTS TO NEXT BYTE 






LA 


R5,l( ,R5) 


COUNT UP ONE BYTE 






CR 


R5,R6 


LAST BYTE OF MAP? 




* 


BM 


LOOP2 


DO AGAIN IF NOT 




* 


RESET 8TH VIRTUAL BLOCK FROM THE CORRESPONDING 




* 


BLOCK ON 


DASD. THIS BLOCK 


NOW CONTAINS ZEROES 




* 


SINCE THE PROGRAM HAS NOT 


YET INVOKED ANY 




* 
* 


SAVE SERVICES AFFECTING IT 


• 






L 


R3, SEVEN 








ST 


R3,OFFS 


INITIALIZE OFFSET 






L 


R3,ONE 








ST 


R3,SPVALUE 


INITIALIZE SPAN 






DIV 


RESET, ID=TESTID, 




X 






SPAN=SPVALUE , OFFSET=OFFS 






LTR 


R15,R15 


CHECK IF RC IS ZERO 






BNZ 


ERROR 


RESET FAILED 





( 
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Processing a Data-in- Virtual Object (continued) 

The program saves the window in the first eight blocks of the object by issuing the DIV macro, 
specifying SAVE. Then it terminates its use of the object by invoking the UNMAP, 
UNACCESS, and UNIDENTIFY services of the DIV macro. 



) 



INVOKE SAVE, USING DEFAULTS FOR SPAN AND 
OFFSET. THIS SAVES * BLOCKS. THE FIRST 
SEVEN ARE FILLED WITH X'll* AND THE LAST 
HAS ALL BINARY ZEROES. 

DIV SAVE,ID=TESTID,SIZE=OBJSIZE 

LTR R15,R15 CHECK ZERO RC 

BNZ ERROR SAVE FAILED 

INVOKE THE UNMAP SERVICE 

DIV UNMAP, ID=TESTID,AREA=MAPPTR1 

LTR R15,R15 CHECK IF RC IS ZERO 

BNZ ERROR UNMAP FAILED 

THE OBJECT NOW HAS SEVEN CONTIGUOUS BLOCKS OF 
l'S, FOLLOWED BY ONE BLOCK OF O'S, FOLLOWED BY 
EIGHT BLOCKS OF 5'S. NOW INVOKE UNACCESS. 



UNACCESS , ID=TESTID 



DIV 

LTR R15,R15 

BNZ ERROR 



CHECK IF RC IS ZERO 
UNACCESS FAILED 



INVOKE THE UNIDENTIFY SERVICE 



ERROR 



EXIT 



B 

EQU 

L 

ST 

EQU 

DIV 

LTR 

BZ 

L 

ST 



EXIT 
* 

R15, SIXTEEN 

R15,SAVER15 
* 



SKIP ERROR PROCESSING 

BAD RETURN CODE 
HOLD R15 VALUE 



UNIDENTIFY , ID=TESTID 



R15,R15 

FREE 

R15, SIXTEEN 

R15,SAVER15 



CHECK IF RC IS ZERO 
IF SO, LEAVE RC GOOD 
SET BAD RETURN CODE 
HOLD R15 VALUE 
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Processing a Data-in- Virtual Object (continued) 

Finally, the program frees its virtual storage and goes through a standard exit linkage 
sequence. 



* 
* 


FREE STORAGE AND EXIT 


FREE 


EQU * 






FREEMAIN RU,A=MAPPTR1,LV=16*4096 , SP=0 




L R15,SAVER15 


RETRIEVE R15 




L R13,4(R13) 


STD EXIT LINKAGE 




L R14,12(R13) 






LM R0,R12,20(R13) SAVE RETURN CODE 




BR R14 




* 


SPACE 2 




* 
* 


DECLARE VARIABLES 




MAPPTR1 


DS A 


PTR TO GETMAINED STORAGE 


OBJSIZE 


DS F 


SIZE RETURNED FROM ACCESS 


OFFS 


DS A 


POSITION IN OBJECT 


SP VALUE 


DS A 


LENGTH TO BE MAPPED-RESET 


SAVER 15 


DS F ' ' 


RC VALUE IN REG 15 


SAVEAREA DS CL72 


USED BY DATA-IN-VIRTUAL 


TESTID 


DS CL8 


ID RETURNED FROM IDENTIFY 


DDNAME 


DS CL8 
ORG DDNAME 






DC AL1(7) 


LENGTH OF DDNAME 




DC CL7 1 DYNAMIC 


NAME USED IN JCL 




ORG DDNAME+8 




* 


SPACE 2 




* 
* 


CONSTANTS 




Nil 


DC X'll' 


HEX ONES 


N55 


DC X'55' 


HEX FIVES 


ONE 


DC F'l' 


ONE 


SEVEN 


DC F'7' 


SEVEN 


EIGHT 


DC F'8' 


EIGHT 


SIXTEEN 


DC F» 16 f 


SIXTEEN 


PAGE 8 
* 


DC F'32768 1 


8 TIMES 4096 


* 


REGISTERS 


RO 


EQU 




Rl 


EQU 1 




R2 


EQU 2 




R3 


EQU 3 




R5 


EQU 5 




R6 


EQU 6 




R12 


EQU 12 




R13 


EQU 13 




R14 


EQU 14 




R15 


EQU 15 

EJECT 

END SAMPLE 





« 
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Performance Considerations 



) 



When an application reads more input and writes more output data than necessary, the 
unnecessary reads and writes impact performance. The improved performance that can be 
expected from data-in-virtual comes from a reduction in the amount of unnecessary I/O. 

As an example of unnecessary I/O, consider the I/O performed by an interactive application 
that requires immediate access to several large data sets. The program knows that some of the 
data, although not all of it, will be accessed. However, the program does not know ahead of 
time which data will be accessed. A possible strategy for gaining immediate access to all the 
data is to read all the data ahead of time, reading each data set in its entirety insofar as this is 
possible. Once read into main storage, the data can be accessed quickly. However, if only a 
small percentage of the data is likely to be accessed during any given period, the I/O performed 
on the unaccessed data is unnecessary. 

Furthermore, if the application changes some data in main storage, it might not keep track of 
the changes. Therefore, to guarantee that all the changes are captured, the application might 
then write entire data sets back onto permanent storage even though only relatively few bytes 
are changed in the data sets. 

Whenever such an application starts up, terminates, or accesses different data sets in an 
alternating manner, time is spent reading data that is not likely to be accessed. This time is 
essentially wasted, and the amount of it is proportional to the amount of bypassed data for 
which I/O is performed. Such applications are suitable candidates for a data-in-virtual 
implementation. 



Factors Affecting Performance 



) 



When applications are implemented using the techniques of data-in-virtual, the unnecessary I/O 
does not take place and the performance can be expected to improve. If the same application is 
first implemented using conventional access methods, and then implemented a second time 
using data-in-virtual techniques, the performance differential between the first implementation 
and the second is a combined function of two factors: the size of the data set and its access 
pattern. To obtain significant performance improvements, both factors must be present in the 
application: 

• Pattern refers to the pattern in which the application references the data. If the pattern is 
process-driven, non-pervasive and scattered unpredictably throughout the data set, the 
data-in-virtual implementation will have the better performance. 

• Size refers to the magnitude of the data sets that the application must process. The larger the 
data sets, the more the performance differential between the two implementations, and the 
data-in-virtual implementation will have the better performance. 

Engineering and scientific applications often use data access patterns that are suitable for 
data-in-virtual. Among the applications that can be considered for a data-in-virtual 
implementation are: 

• Applications that process large arrays 

• VSAM relative record applications 

• BDAM fixed length record applications 
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On the other hand, commercial applications often use data access patterns that are not suitable 
because they are predictable and sequential. If the access pattern of a proposed application is 
fundamentally sequential or if the data set is small, a conventional VSAM (or other sequential 
access method) implementation may perform better than a data-in-virtual implementation. 
However, this does not rule out commercial applications as data-in-virtual candidates. If the 
performance factors are favorable, any type of application, commercial or scientific, is suitable 
for a data-in-virtual implementation. 



< 
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Real Storage Management 



) 



) 



The real storage manager (RSM) administers the use of real storage and directs the movement 
of virtual pages between auxiliary storage and real storage in page size (4096 bytes) blocks. It 
makes all addressable virtual storage in each address space appear as real storage. Only virtual 
pages necessary for program execution are kept in real storage, the remainder reside on 
auxiliary storage. RSM employs the auxiliary storage manager (ASM) of the Data Manager to 
perform the actual paging I/O necessary to transfer pages in and out of real storage. ASM also 
provides DASD allocation and management for paging I/O space on auxiliary storage. RSM 
relies on the system resources manager (SRM) for guidance in the performance of some of its 
operations. 

RSM assigns storage page frames upon request from four pools of available frames, thereby 
associating virtual addresses with real storage addresses. Frames are repossessed upon 
termination of use, when freed by a user, when a user is swapped-out, or when needed to 
replenish an available pool. While a virtual page occupies a real storage frame, the page is 
considered pageable unless specified otherwise as a system page that must be resident in real 
storage. RSM also allocates virtual equals real (V = R) regions upon request by those programs 
that cannot tolerate dynamic relocation. Such a region is allocated contiguously from a 
predefined area of real storage and is non-pageable. Programs in this region do run in 
translation mode, although addressing is one to one virtual to real. 

The paging services provided in MVS/XA include the following: 

• PGRLSE or PGSER, RELEASE parameter - Release the virtual storage contents 

• PGLOAD or PGSER, LOAD parameter - Load the virtual storage areas into real storage 

• PGOUT or PGSER, OUT parameter - Page out the virtual storage areas from real storage 

The page release function allows the user and the system to make available space in both real 
storage and auxiliary storage that is known to be of no future use. Proper use of this function 
can increase the amount of storage available to the system and prevent needless paging I/O 
activity. Usage of page release may improve operating efficiency when the using program can 
discard the contents of a large virtual storage area (circumscribing one or more pages) and 
reuse the virtual storage pages; paging operations may be eliminated for those virtual storage 
pages when they are reused. 

The proper use of the page load and page out functions will tend to decrease system overhead 
resulting from page faults and to clean out of real storage those pages no longer required for 
program execution or not required for some period in the future. 
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Relinquishing Virtual Storage 



When an area of virtual addressable storage within your program no longer has significant 
contents, you can make this storage available by issuing a PGRLSE macro instruction or by 
issuing the PGSER macro instruction with the RELEASE parameter specified. These macro 
instructions make available all real and external page storage wholly associated with the area of 
virtual address space specified. As shown in Figure 41, if the specified addresses are not on 
page boundaries, the low address is rounded up and the high address is rounded down; then, 
the pages contained between the addresses are released. The virtual space remains, but its 
contents are forfeited. When the using program can discard the contents of a large virtual area 
(one or more complete pages) and reuse the virtual space without the necessity of paging 
operations, the page release function may improve operating efficiency. 




address 1 
(low) 



address 2 
(high) 



Figure 41. Releasing Virtual Storage 

All storage obtained for your program by the GETMAIN macro instruction is automatically 
freed by the control program when the job step terminates. Freeing storage in this manner 
requires no action on your part. When you issue a FREEMAIN macro instruction, 
FREEMAIN does the equivalent of a page release for any resulting free page and the page is 
no longer available to the issuer. 



| 



Loading/Paging Out Virtual Storage Areas 



The PGLOAD macro instruction and the PGSER macro with the LOAD parameter specified 
essentially provide a page-ahead function. By loading specified virtual storage areas into real 
storage, you can attempt to ensure that certain pages will be in real storage when needed. Page 
faults can occur, however, and these pages may be paged out. 

With the page-load function, you have the option of specifying that the contents of the virtual 
area is to remain intact or be released. If you specify RELEASE = Y, the current contents of 
entire virtual 4K pages to be brought in may be discarded and new real frames assigned without 
page-in operations; if you specify RELEASE = N, the contents are to remain intact and be used 
later. 

If you specify PGLOAD with RELEASE = Y or PGSER with LOAD and RELEASE = Y, the 

page release function will be performed before the page load function. That is, no page-in is 
needed for areas defining entire virtual pages since the contents of those pages are expendable. 



The page-out function initiates page-out operations for specified virtual address pages that are 
in real storage. The real storage frames will be made available for reuse upon completion of 
the page-out operation unless you specify the KEEPREL parameter in the macro instruction. 



< 
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S 



An area that does not encompass one or more complete pages will be copied to auxiliary 
storage, but the real frames will not be freed. 



Virtual Subarea List (VSL) 



The virtual subarea list provides the basic input to the page service functions that use a 24-bit 
interface: PGLOAD, PGRLSE, and PGOUT. The list consists of one or more doubleword 
entries, each entry describing an area of virtual storage. The list must be nonpageable and 
contained in the address space of the subarea to be processed. 



Each parameter list entry has the following format: 



Byte 12 3 

FLAGS START ADDRESS 



4 5 6 7 

FLAGS END ADDRESS + 1 



) 



Byte Flags 




BitO 


) 


Bit 1 


(•1 ) 


Bit 2 


(-1 ) 


Bit 3 


(...1 ....) 


Bit 4 


(.... 1...) 


Bit 5 


( I-) 


Bit 6 


( 1) 


Bit 7 


( 1) 



This bit indicates that bytes 1-3 are a chain pointer to the next VSL entry to be processed; 

bytes 4-7 are ignored. This feature allows several parameter lists to be chained as a single 

logical parameter list. 

Reserved. 

Reserved. 

PGLOAD is to be performed; reserved, set by macro instruction. 

PGRLSE is to be performed; reserved, set by macro instruction. 

Reserved. 

Reserved. 

Reserved. 



Start Address: 

The virtual address of the origin of the virtual area to be processed. 



Byte 4 Flags: 




BitO 


(1 ) 


Bit 1 


(.1 ) 


Bit 2 


(..1 ) 


Bit 3 


(...1 ....) 


Bit 4 


(.... 1...) 


Bit 5 


( 1..) 


Bit 6 


( 1.) 


Bit 7 


(.... ...1) 



This flag indicates the last entry of the list. It is set in the last doubleword entry in the list. 

When this flag is set, the entry in which it is set is ignored. 

Reserved. 

This flag indicates that a return code of 4 was issued from a page service function other than 

PGRLSE. 

Reserved. 

PGOUT is to be performed; reserved, set by macro instruction. 

KEEPREL option of PGOUT is to be performed; reserved, set by macro instruction. 

Reserved. 



End Address + 1: 

The virtual address of the byte immediately following the end of the virtual area. 



Page Service List (PSL) 



The page services list provides the basic input to the page service function for the PGSER 
macro instruction. You can specify either 24-bit or 31 -bit addresses in the PSL entries. Each 
PSL entry specifies the range of addresses for which a service is to be performed or points to 
the first PSL entry in a new list of concatenated PSL entries that are to be processed. Within a 
PSL entry, you can also nullify a service on a range of addresses by indicating that you do not 
want to perform the service for that range. 



) 
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Each 12-byte PSL entry has the following form: 

Bytes Meaning 

0-3 Bit of byte must be 0. The remainder of these bytes contains the 31 -bit starting address for which the page 

service is to be performed or a pointer to the next PSL. 

4-7 Bit of byte 4 must be 0. If bytes 0-3 contain the starting address, these bytes contain the address of the last 

byte for which the page service is to be performed. If bytes 0-3 contain a pointer to the next PSL, these bytes 
are reserved. 

8 Flags set by the caller as follows: 

Bit Meaning 

Set to 1 to indicate that this is the last PSL entry in a concatenation of PSL entries. 

1 Set to 1 to indicate that no services are to be performed for the range of addresses specified. 

2 Set to 1 to indicate that bytes 0-3 contain a pointer to the next PSL. 

9-1 1 Set by the PGSER service routine. 



I 
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Miscellaneous Services 



Timing Services 



Interval timing is a standard feature of MVS/XA. It provides the ability to request the date 
and time of day and provides for setting, testing, and canceling intervals of time. 



Date and Time of Day 



) 



The operator is responsible for initially supplying the correct date and the time of day in terms 
of a 24-hour clock. You request the date and time of day using the TIME macro instruction. 
The control program returns the date in register 1 and the time of day in register or in a 
doubleword that you supply if you specify the MIC or STCK parameter. 

If ZONE = GMT is specified, the returned time of day and date will be for Greenwich Mean 
Time. If ZONE = LT is specified or if the ZONE parameter is omitted, the local time of day 
and date will be returned. However, if STCK is specified, the ZONE parameter will be 
ignored. 

All references to time of day use the time-of-day (TOD) clock, a 64-bit binary counter. The 
TOD clock runs continuously while the power is on; the clock is not affected by the system 
stop-conditions. The operator normally sets the clock only after an interruption of CPU power 
has caused the clock to stop, and restoration of power has restarted it. The operator sets the 
clock during system initialization in response to a system message. (For more information 
about the TOD clock, see Principles of Operation.) 



Interval Timing 



J ■ 



Time intervals up to 24 hours in length can be established for any task in the job step through 
the use of the STIMER or STIMERM SET macro instructions. The time remaining in an 
interval established via the STIMER macro can be tested or cancelled through the use of 
TTIMER macro instruction. The time remaining in an interval established via the STIMERM 
SET macro instruction can be cancelled or tested through the use of the STIMERM CANCEL 
or STIMERM TEST macro instructions. 

The value of the CPU timer can be obtained by using the CPUTIMER macro instruction. The 
CPU timer is used to track task-related time intervals. 

The TASK, REAL, or WAIT parameters of the STIMER macro instruction and the 
WAIT = YES|NO parameter of the STIMERM SET macro instruction specify the manner in 
which the time interval is to be decreased. REAL and WAIT indicate the interval is to be 
decreased continuously, whether the associated task is active or not. TASK indicates the 
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interval is to be decreased only when the associated task is active, 
establish real time intervals only. 



STIMERM SET can 



If REAL or TASK is specified on STIMER or WAIT = NO is specified on STIMERM SET, 
the task continues to compete with the other ready tasks for control; if WAIT is specified on 
STIMER, or WAIT = YES is specified on STIMERM SET, the task is placed in a WAIT 
condition until the interval expires, at which time, the task is placed in the ready condition. 

When TASK or REAL is specified on STIMER or WAIT = NO is specified on STIMERM 
SET, the address of an asynchronous timer completion exit routine can also be specified. This 
routine is given control sometime after the time interval completes. The delay is dependent on 
the system's work load and the relative dispatching priority of the associated task. If an exit 
routine is not specified, there is no notification of the completion of the time interval. The exit 
routine must be in virtual storage when specified, must save and restore registers as well as 
return control to the address in register 14. 

Timing services does not serialize the use of asynchronous timer completion routines. 

Figure 42 shows the use of a time interval when testing a new loop in a program. The 
STIMER macro instruction sets a time interval of 5.12 seconds, which is to be decreased only 
when the task is active, and provides the address of a routine called FIXUP to be given control 
when the time interval expires. The loop is controlled by a BXLE instruction. 



STIMER TASK, FIXUP, BINTVL=TIME Set time interval 



LOOP 



NG 



TM TIMEXP,X'01 

BC 1,NG 

BXLE 12, 6, LOOP 

TTIMER CANCEL 





USING 


FIXUP, 15 


FIXUP 


SAVE 


(14,12) 




01 


TIMEXP, X' 01 » 




RETURN 


(14,12) 


TIME 


DC 


X'00000200' 


TIMEXP 


DC 


X'OO' 



Test if FIXUP routine entered 
Go out of loop if time interval expired 
If processing not complete, repeat loop 
If loop completes, cancel remaining time 



Provide addressability 

Save registers 

Time interval expired, set switch in loop 



Restore registers 



Timer is 5.12 seconds 
Timer switch 



Figure 42. Interval Processing 



The loop continues as long as the value in register 12 is less than or equal to the value in 
register 6. If the loop stops, the TTIMER macro instruction causes any time remaining in the 
interval to be canceled; the exit routine is not given control. If, however, the loop is still in 



( 
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effect when the time interval expires, control is given to the exit routine FIXUP. The exit 
routine saves registers and turns on the switch tested in the loop. The FIXUP routine could 
also print out a message indicating that the loop did not go to completion. Registers are 
restored and control is returned to the control program. The control program returns control 
to the main program and execution continues. When the switch is tested this time, the branch 
is taken out of the loop. Caution should be used to prevent a timer exit routine from issuing an 
STIMER specifying the same exit routine. An infinite loop may occur. 

The priorities of other tasks in the system may also affect the accuracy of the time interval 
measurement. If you code REAL or WAIT, the interval is decreased continuously and may 
expire when the task is not active. (This is certain to happen when WAIT is coded.) After the 
time interval expires, assuming the task is not in the wait condition for any other reason, the 
task is placed in the ready condition and then competes for CPU time with the other tasks in 
the system that are also in the ready condition. The additional time required before the task 
becomes active will then depend on the relative dispatching priority of the task. 

The STIMER macro instruction should not be issued while a BTAM OPEN or LINE OPEN 
operation is in progress, since the BTAM OPEN LINE routines also use STIMER. STIMER 
should not be issued before invoking dynamic allocation because dynamic allocation can also 
issue STIMER. 



Communicating with the System Operator 



> 



The WTO and the WTOR macro instructions allow you to write messages to the operator. The 
WTOR macro instruction also allows you to request a reply from the operator. Messages can 
be sent to (and replies received from) as many as 99 operator consoles. Only standard, 
printable EBCDIC characters, shown in Figure 43, appear on the console. All other characters 
are replaced by blanks. If the terminal does not have dual-case capability, it prints lowercase 
characters as uppercase characters. 



Hex 


EBCDIC 


Hex 


EBCDIC 


Hex 


EBCDIC 


Hex 


EBCDIC 


Code 


Character 


Code 


Character 


Code 


Character 


Code 


Character 


40 


(space) 


7B 


# 


99 


r 


D5 


N 


4A 





7C 


@ 


A2 


s 


D6 





4B 




7D 




A3 


t 


D7 


P 


4C 


< 


7E 


= 


A4 


u 


D8 


Q 


4D 


( 


7F 


" 


A5 


V 


D9 


R 


4E 


+ 


81 


a 


A6 


w 


E2 


S 


4F 


1 


82 


b 


A7 


X 


E3 


T 


50 


& 


83 


c 


A8 


y 


E4 


U 


5A 


t 


84 


d 


A9 


z 


E5 


V 


5B 


$ 


85 


e 


CI 


A 


E6 


w 


5C 


* 


86 


f 


C2 


B 


E7 


X 


5D 


) 


87 


g 


C3 


C 


E8 


Y 


5E 




88 


h 


C4 


D 


E9 


z 


5F 


I 


89 


i 


C5 


E 


F0 





60 


- 


91 


j 


C6 


F 


Fl 


1 


61 


/ 


92 


k 


C7 


G 


F2 


2 


6B 




93 


1 


C8 


H 


F3 


3 


6C 


% 


94 


m 


C9 


I 


F4 


4 


6D 


— 


95 


n 


Dl 


J 


F5 


5 


6E 


> 


96 





D2 


K 


F6 


6 


6F 


? 


97 


P 


D3 


L 


F7 


7 


7A 




98 


q 


D4 


M 


F8 
F9 


8 
9 



w 



Figure 43. Characters Printed or Displayed on an MCS Console 
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Notes: 

1. If the display device or printer is defined to JES3, the following characters are also translated 
to blanks: 

I / ; -i : " 

2. The system recognizes the following hexadecimal representations of the U.S. national 
characters: @ as X'7C; $ as X'5B'; and # as X'7B'. In countries other than the U.S., the 
U.S. national characters represented on terminal keyboards might generate a different 
hexadecimal representation and cause an error. For example, in some countries the $ 
character generates a X'4A '. 

There are two basic forms of the WTO macro instruction: the single-line form, and the 
multiple-line form. 

The following should be considered when issuing multiple-line WTO messages (MLWTO). 

• Only the first line of a multiple-line WTO message is passed to the installation-written 
WTO exit routine (IEECVXIT). 

• When a console switch takes place, unended multiple-line WTO messages and multiple-line 
WTO messages in the process of being written to the original console are not moved to the 
new console. 

• When a hard copy switch takes place from the system log to an active operator's console, 
MLWTO messages in the process of being written to the system log are not moved to the 
new hard copy device. 

• The left-most three bytes of register zero must be zero for a multiple-line message. You 
must ensure that this is done. 

• When the system hard copy log is an active operator's console, only the hard copy versions 
of multiple-line messages are written to the console. 

• Because the hard copy log receives a copy of every message in the system, use an active 
operator's console as the hard copy log only in an emergency. 

See the macro instructions section for an explanation of the parameters in the single-line and 
multiple-line forms of the WTO macro instruction. 

The message is routed using the routing codes specified in the WTO macro instruction. At 
system generation, each operator's console in the system is assigned routing codes that 
correspond to the functions that the installation wants that console to perform. When any of 
the routing codes assigned to a message match any of the routing codes assigned to a console, 
the message is sent to that console. 

Disposition of the message is indicated through the descriptor codes specified in the WTO 
macro instruction. Descriptor codes classify WTO messages so that they can be properly 
presented on, and deleted from, display devices. Each WTO macro instruction should contain 
at least one descriptor code. The descriptor code is not printed or displayed as part of the 
message text. 

If the user supplies a descriptor code in the WTO macro instruction, an indicator is inserted at ■ 

the start of the message. The indicators are: a blank, an at sign (@), an asterisk (*), or a blank ^ 
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followed by a plus sign ( + ). The indicator inserted in the message depends on the descriptor 
code that the user supplies and whether the user is a privileged or APF-authorized program or a 
non-authorized problem program. Figure 44 shows the indicator that is used for each 
descriptor code. 



Descriptor 
Code 

1 

2 

3-10 

11 

12-16 



Privileged or 
APF-Authorized Program 



blank 
* 

blank 



Non-Authorized 
Problem Program 



blank + 

@ 
blank + 



Figure 44. Descriptor Code Indicators 

The indicator @ or * informs operators that they must take some immediate or critical eventual 
action. A critical eventual action is an action that the operator must perform, as soon as 
possible, in response to a critical situation during the operation of the system. For example, if 
the dump data set is full, the operator is notified to mount a new tape on a specific unit. This 
is considered a critical action because no dumps can be taken until the tape is mounted; it is 
eventual rather than immediate because the system continues to run and processes jobs that do 
not require dumps. 

If a problem program issues a message with descriptor code of 1 or 2, descriptor code 7 is 
forced so that the message is deleted at address space or task termination. For more 
information concerning routing and descriptor codes, see Routing and Descriptor Codes. 

If an application that uses WTO needs to alter a message each time the message is issued, the 
list form of the WTO macro may be useful. The message area, which is referenced by the WTO 
parameter list, can be altered before you issue the WTO. The message length, which appears in 
the WTO parameter list, does not need to be altered if you pad out the message area with 
blanks. 

A sample WTO macro instruction is shown in Figure 45. 



Single-line WTO 
format 

Multiple- WTO 
line format 
(list form) 



'BREAKOFF POINT REACHED. 
ROUTCDE=14 , DESC=7 



TRACKING COMPLETED . • , C 



('SUBROUTINES CALLED' ,C), C 

('ROUTINE TIMES CALLED ' ,L) , (' SUBQUER ' ,D) , C 

( 'ENQUER' ,D) ,( 'WRITER 1 ,D) , C 

( ' DQUER • , DE ) , C 
ROUTCDE= (2,14), DESC= (7,8), MF=L 



Figure 45. Writing to the Operator 



) 



To use the WTOR macro instruction, code the message exactly as designated in the single-line 
WTO macro instruction. (The WTOR macro instruction cannot be used to pass multiple-line 
messages.) When the message is written, the control program adds a two-character message 
identifier before the message to associate the reply with the message. The control program also 
inserts an indicator as the first character of all WTOR messages, thereby informing the operator 
that immediate action is required. You must, however, indicate the response desired. In 
addition, you must supply the address of the area in which the control program is to place the 
reply, and you must indicate the length of the reply. The length of the reply may not be zero. 
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You also supply the address of an event control block which the control program posts after 
the reply has been placed, left-adjusted, in your designated area. 

A sample WTOR macro instruction is shown in Figure 46. The reply is not necessarily 
available at the address you specified until a WAIT macro instruction has been issued. 



XC ECBAD, ECBAD Clear ECB 

WTOR 'STANDARD OPERATING CONDITIONS? REPLY YES OR NO', C 

REPLY , 3 , ECBAD , ROUTCDE= ( 1 , 15 ) 
WAIT ECB=ECBAD 



ECBAD DC F'O' Event control block 

REPLY DC C'bbb 1 Answer area 



Figure 46. Writing to the Operator With a Reply 

When a WTOR macro instruction is issued, any console receiving the message has the authority 
to reply. The first reply received by the control program is returned to the issuer of the 
WTOR, providing the syntax of the reply is correct. If the syntax of the reply is not correct, 
another reply is accepted. The WTOR is satisfied when the control program moves the reply 
into the issuer's reply area and posts the event control block. Each console that received the 
original WTOR will also receive the accepted reply unless it's a security message. No console 
receives the accepted reply to a security message. The master console may answer any WTOR, 
even if it did not receive the original message. 



Writing to the Programmer 



The WTO and the WTOR macro instructions allow you to write messages to the programmer, 
as well as to the operator. However, only the operator can reply to a WTOR message. 

To write a message to the programmer, you must specify ROUTCDE = 1 1 in the WTO or the 
WTOR macro instruction. 



Writing to the System Log 

The system log consists of one SYSOUT data set on which the communication between the 
operator and the system is recorded. You can use the system log by coding the information 
that you wish to log in the "text" parameter of the WTL macro instruction. 

When the WTL macro instruction is executed, the control program places your text in one of 
the buffers and, when the buffer is full, writes the buffer onto the system log data set. The 
control program writes the text of your WTL macro instruction on the master console instead 
of on the system log if the system log is not active. 

Although when using the WTL macro instruction you code the message within apostrophes, the 
written message does not contain the apostrophes. The message can include any character that 
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is valid for the WTO macro instruction and is assembled and written the same way as the WTO 
macro instruction. MCS routing codes and descriptor codes are not assigned, since they are not 
needed by the WTL macro instruction. 

Note: The exact format of the output of the WTL macro instruction varies depending on the 
job entry system (JES2 or JES3) that is being used, the output class that is assigned to the log 
at system initialization, and whether DLOG is in effect for JES3. In JES3, system log entries 
are preceded by a 23-character prefix 

that includes a time stamp and routing information. If the combined prefix and message 
exceeds 126 characters, the log entry is split at the first blank or comma encountered when 
scanning backward from the 126th character of the combined prefix and message. See 
Operations: JES3 Commands for information about the format of the log entry when using 
JES3. 



Message Deletion 
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When using a display console, messages that are no longer necessary can be deleted 
from the operator's screen by the programmer. The control program assigns a message 
identification number to each WTO and WTOR message and returns the message 
identification number in register 1 . The DOM macro instruction uses the identification 
number to indicate which message is to be deleted. The message identification number must 
not be confused with the reply identification number that is assigned to WTOR replies. 

Deleting messages is simplified by the TOKEN parameter of the DOM, WTO, and WTOR 
macros. TOKEN identifies a unique 4-byte ID that you originate and associate with one or 
more messages when you issue a WTO or WTOR. Then you can use the same token ID when 
you issue a DOM macro to delete all the messages that are associated with the ID. 

When you you want to delete several (up to 60) messages with a single DOM invocation, 
you can use the COUNT parameter with MSGLIST. Count is used to indicate the number of 
messages in the message list. The high order bit of each message ID in the message list must 
be zero. 

You can also use the DOM macro instruction to keep WTOR messages from appearing, or 
erase them if they have already appeared, by specifying REPLY = YES on the macro. 
The issuer of the DOM with REPLY = YES must be a task in the same job step and 
address space as the issuer of the WTOR macro instruction or must be a task executing in 
supervisor state, in key 0-7, or authorized by APF. 

Because all outstanding WTOs that were issued with a descriptor code of 7 are deleted at 
address space or task termination, it is possible for a WTO to be deleted without ever being 
displayed. If a task terminates and the JES global processor is not active or if the console to 
which the message is routed is backed up, the message is deleted. 
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Part II: Macro Instructions 



You can communicate service requests to the control program using a set of macro instructions 
provided by IBM. These macro instructions are available only when programming in the 
assembler language, and are processed by the assembler program using macro definitions 
supplied by IBM and placed in the macro library when the system was generated. 

The processing of the macro instruction by the assembler program results in a macro expansion, 
generally consisting of data and executable instructions in the form of assembler language 
statements. The data fields are the parameters to be passed to the requested control program 
routine; the executable instructions generally consist of a branch around the data, instructions 
to load registers, and either a branch instruction or a supervisor call (SVC) to give control to 
the proper program. The exact macro expansion appears as part of the assembler output 
listing. 

Applications programmers can use the macro instructions described in this publication without 
restriction. Some macro instructions contain parameters that are restricted to systems 
programmers and installation-approved personnel. These parameters, as well as 
installation-controlled macro instructions, are described in SPL: System Macros and Facilities. 



Selecting the Macro Level 



■wjjp 



Certain MVS/XA macro expansions cannot execute on an MVS/370 system. These macros are 
downward incompatible. Parameters that are new for MVS/XA are not supported by the 
MVS/370 versions of the downward incompatible macros. In some cases the new parameters 
are ignored, in other cases they cause assembly errors. Callers executing in 31 -bit addressing 
mode must use the MVS/XA version of these downward incompatible macro instructions. The 
following macro instructions are the downward incompatible macros described in this book: 

• ATTACH 

• ESTAE 

• EVENTS 

• STIMER 

• WTOR 

The SPLEVEL macro instruction solves the problems associated with downward incompatible 
macros. The SPLEVEL macro instruction allows an installation to assemble programs using 
the MVS/XA macro library and to select either the MVS/370 or the MVS/XA version of the 
downward incompatible macros. 

Before issuing a downward incompatible macro, users can specify the macro level that they 
want. They do this by issuing the SPLEVEL macro using the SET=« option, with n = 1 or 2. 
If n = 1, the MVS/370 expansion of the macro code is generated and if n = 2, the MVS/XA 
expansion of the macro code is generated. If the user does not specify the value of n, the 
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SPLEVEL routine uses the default value of 2. See SPL: System Modifications for information 
concerning the way in which an installation can change this default. 

A user can also select the level of the macro at execution time, based on the system that is 
operating. The example in Figure 47 shows one method of selecting the macro level. The 
example uses the WTOR macro instruction, but any downward incompatible macro instruction 
could be substituted. The code makes use of the fact that the CVTMVSE bit in byte CVTDCB 
(located at offset 116 or X'74' of the communications vector table (CVT)) is set to 1 when 
System Product Version 2 is operating. The CVTMVSE field of the CVT is defined in System 
Product Version 2. 



* DETERMINE WHICH SYSTEM IS EXECUTING 

TM CVTDCB , CVTMVSE 
BO SP2 

* INVOKE MVS/370 VERSION OF THE MACRO 

SPLEVEL SET=1 

WTOR 

B CONTINUE 

* INVOKE MVS/XA VERSION OF THE MACRO 
SP2 SPLEVEL SET=2 

WTOR 

* RESET TO SYSTEM DEFAULT 
CONTINUE SPLEVEL SET 



Figure 47. Macro Level Selected at Execution Time 

The SPLEVEL macro instruction is also described in SPL: System Macros and Facilities. 



Addressing Mode and the Macro Instructions 



Callers in either 24-bit or 31 -bit addressing mode can invoke most of the macros described in 
this book. The following is a list of the macro instructions, documented in Part II of this book, 
that require the caller to be executing in 24-bit addressing mode and require that the parameters 
be located in 24-bit addressable storage: 

FRACHECK 

RACHECK 

RACROUTE 

RACSTAT 

SEGLD 

SEGWT 

SPIE 

Note: RACF services are also available through the RACROUTE macro, which can execute in 
either 24-bit or 31 -bit addressing mode. 

All addresses specified as parameters for the other macro instructions in this book can be 31 -bit 
addresses unless otherwise stated. If a parameter passed by a program executing in 31 -bit 
addressing mode must be located in 24-bit addressable storage, the restriction is stated in the 
description of the macro instruction. 

( 
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In general, a program executing in 24-bit addressing mode cannot pass parameters located 
above 16 Mb in virtual storage to a system service. There are exceptions to this general rule. 
For example, a program executing in 24-bit addressing mode can: 

• Free storage above 16 Mb using the FREEMAIN macro instruction 

• Allocate storage above 16 Mb using the GETMAIN macro instruction 

• Perform cell pool services for cell pools located in storage above 16 Mb using the CPOOL 
macro instruction 

• Perform page services for storage locations above 16 Mb using the PGSER macro 
instruction 

See the descriptions of the individual macro instructions for details. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
these macro instructions: 

ATTACH 

CALL 

ESTAE 

EVENTS 

LINK 

SETRP 

STIMER 

SYNCH 

WTOR 

XCTL 



Macro Instruction Forms 

When written in the standard form, some of the macro instructions result in instructions that 
store into an inline parameter list. The option of storing into an out-of-line parameter list is 
provided to allow the use of these macro instructions in a reenterable program. You can 
request this option through the use of list and execute forms. When list and execute forms exist 
for a macro instruction, their descriptions follow the description of the standard form. 

Use the list form of the macro instruction to provide a parameter list to be passed either to the 
control program or to a problem program, depending on the macro instruction. The expansion 
of the list form contains no executable instructions; therefore registers cannot be used in the list 
form. 

Use the execute form of the macro instruction in conjunction with one or two parameter lists 
established using the list form. The expansion of the execute form provides the executable 
instructions required to modify the parameter lists and to pass control to the required program. 
Only the ATTACH, LINK, and XCTL macro instructions use two parameter lists: a problem 
program list, resulting from the address parameter and VL parameters, and a control program 
list, resulting from the remaining parameters. The control program list is required, and the 
problem program list is optional in these macro instructions. 
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If you do not generate the control program parameter list form of the macro, you must provide 
the list yourself, initialize it, then update it (either directly or by explicitly specifying keywords 
on the execute form). 

Note: If the program issuing the execute form of a macro instruction is executing in 24-bit 
addressing mode, the remote control program parameter list must be located in 24-bit 
addressable storage. 

The CALL, DEQ, ENQ, and SNAP macro instructions can result in variable length parameter 
lists. The length of the parameter list generated by the list form of the macro instruction must 
be equal to the maximum length list required by any execute form that refers to the list. The 
maximum length list can be constructed in one of three methods: 

• Code the parameters required for the maximum length execute form in the list form. 

• Provide a DS instruction immediately following the list form to allow for the maximum 
length parameter list. 

• Acquire a maximum length list by using commas in the list form to indicate the maximum 
number of parameters. For example, the STORAGE parameter of the SNAP macro 
instruction could be coded as STORAGE = („„„„) to allow for five pairs of addresses. The 
actual addresses would be provided in the execute forms. 

The descriptions of the following macro instructions assume that the standard begin, end, and 

continue columns are used - for example, column 1 is assumed as the begin column. To change 

the begin, end, and continue columns, code the ICTL instruction to establish the coding format 

you wish to use. If you do not use ICTL, the assembler recognizes the standard columns. To . 

code the ICTL instruction, see Assembler H Version 2 Application Programming: Language (I 

Reference. 
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Coding the Macro Instructions 



The table appearing near the beginning of each macro instruction indicates how the macro 
instruction is to be coded. The table does not explain the meanings of the parameters; the 
parameters are explained following the table. 

Figure 48 shows a sample macro instruction, TEST, and summarizes all the coding information 
that is available for it. The table is divided into three columns, A, B, and C. 



p 



6? 




b 

TEST 
b 



MATH 

(A2) >- HIST 

GEOG 



,DATA= data addr 
-*► ,LNG=ctofo length 



name: symbol. Begin name in column 1 
One or more blanks must precede TEST. 

One or more blanks must follow TEST. 



data addr: RX-type address, or register (2) - (12) 



data length: symbol or decimal digit, with a maximum 
value of 256. 



,FMT=HEX 
,FMT=DEC 
,FMT=BIN 

,PA$S=value 



.grade 



Default: FMT=HEX 



value: symbol, decimal digit, or register (1) or (2) - (12). 
Default: PASS=65 

grade: symbol, decimal digit, or register (1) or (2) - (12). 



Figure 48. Sample Macro Instruction 

• The first column, A, contains those parameters that are required for that macro instruction. 
If a single line appears in that column, Al, the parameter on that line is required and must 
be coded. If two or more lines appear together, A2, one and only one of the parameters on 
the lines must be coded. 

• The second column, B, contains those parameters that are optional for that macro 
instruction. If a single line appears in that column, Bl, the parameter on that line is 
optional. If two or more lines appear together, B2, one and only one of the parameters 
appearing on lines may be coded if desired. 

• The third column, C, provides additional information for coding the macro instruction. 
The following terms can appear in column C. 

symbol: any symbol valid in the assembler language. That is, an alphabetic character followed 
by 0-7 alphameric characters, with no special characters and no blanks. 
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decimal digit: any decimal digit up to the value indicated in the parameter description. If both 
symbol and decimal digit are indicated, an absolute expression is also allowed. 

register (2) - (12): one of general registers 2 through 12, specified within parentheses, 
previously loaded with the right-adjusted value or address indicated in the parameter 
description. The unused high-order bits must be set to zero. The register may be designated 
symbolically or with an absolute expression. 

register (0): general register 0, previously loaded as indicated under register (2) - (12) above. 
Designate the register as (0) only. 

register (1): general register 1, previously loaded as indicated under register (2) - (12) above. 
Designate the register as (1) only. 

RX-type address: any address that is valid in an RX-type instruction (for example, LA). 

A-type address: any address that may be written in an A-type address constant. 

default: a value that is used in default of a specified value, and that is assumed if the 
parameter is not coded. 

Use the parameters to specify the services and options to be performed, and write them 
according to the following general rules: 

• If the selected parameter is written in all capital letters (for example, MATH, HIST, or 
FMT = HEX), code the parameter exactly as shown. 

• If the selected parameter is written in italics (for example, grade) substitute the indicated 
value, address, or name. 

• If the selected parameter is a combination of capital letters and italics separated by an 
equal sign (for example, DATA = data addr) code the capital letters and equal sign as 
shown, and then make the indicated substitution for the italics. 

• Read the table from top to bottom, and code the parameters in the order shown. Code 
commas and parentheses exactly as shown. 

• If you select a parameter to be coded, read the third column, C, before proceeding to the 
next parameter. Column C often contains notes pertaining to restrictions on coding the 
parameters. 
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Continuation Lines 



You can continue the parameter field of a macro instruction on one or more additional lines 
according to the following rules: 

1. Enter a continuation character (not blank, and not part of the parameter coding) in column 
72 of the line. 

2. Continue the parameter field on the next line, starting in column 16. All columns to the 
left of column 16 must be blank. 

You can code the parameter field being continued in one of two ways. Code the parameter 
field through column 71, with no blanks, and continue in column 16 of the next line; or 
truncate the parameter field by a comma, where a comma normally falls, with at least one 
blank before column 71, and then continue in column 16 of the next line. Figure 49 shows an 
example of each method. Additional information on the continuation of any assembler 
language macro instruction is provided in the publication Assembler Language. 



) 



1 



NAME1 
NAME2 



10 



I I 



0P1 
0P2 



16 



44 



72 

y y v 

OPERANDI , 0PERAND2, 0PERAND3,0PERAND4, 0PERAND5, 0PERAND6, OPX 
ERAND7 THIS IS ONE WAY 

OPERANDI, 0PERAND2, THIS IS ANOTHER WAY X 
0PERAND3,0PERAND4, ANOTHER x 

0PERAND5,OPERAND6,OPERAND7 WAY 



Jf 



Figure 49. Continuation Coding 
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ABEND — Abnormally Terminate a Task 



The ABEND macro instruction is used to initiate error processing for a task. ABEND can 
request a full or tailored dump of virtual storage areas and control blocks pertaining to the 
tasks being abnormally terminated, and can specify that the entire job step is to be abnormally 
terminated. Before the task is terminated, an ESTAE exit gets control. This exit may recover 
the task and allow it to retry. 

If the job step task is abnormally terminated or if ABEND specifies job step termination, the 
completion code is recorded on the system output device, and the remaining job steps in the job 
are either skipped or executed as specified in their job control statements. 

If the job step is not to be terminated, the following actions are taken: 

• The task that was active when ABEND was issued is terminated, along with all of the 
subtasks of that active task. 

• The completion code is posted as indicated in the completion code parameter description 
below. 

• The end-of-task exit routine specified in the ATTACH macro instruction that created the 
task which issued ABEND is selected to be given control. The exit routine is given control 
when the originating task of the task for which ABEND was issued becomes active. None 
of the end-of-task exit routines specified for any subtasks of the task for which ABEND 
was issued are given control. 

The ABEND macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede ABEND. 
ABEND 

b One or more blanks must follow ABEND. 

comp code comp code: symbol, decimal or hexadecimal digit, or register (1) or (2) - (12). 

Value range: 0-4095 

,REASON = reason code reason code: symbol, decimal or hexadecimal number, or register (2) - (12). 

,DUMP code type: USER or SYSTEM. 

„STEP Default: code type = USER. 

,„code type 

,DUMP,STEP 

,DUMP„code type 

„STEP,code type 

,DUMP,STEP,cocfe type 

,DUMPOPT -parm list addr parm list addr: RX-type address, or register (2) - (12). 



The parameters are explained as follows: 

comp code 

specifies the completion code associated with the abnormal termination. If the job step is 
to be terminated, the decimal representation of the user completion code or the 
hexadecimal representation of the system completion code is recorded on the system 
output device. If the job step is not to be terminated, the completion code is placed in the 
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TCB of the active task, and in the ECB specified in the ECB parameter of the ATTACH 
macro instruction issued to create the active task. If you specify a hexadecimal digit, you 
must use X'dd' format to distinguish the hexadecimal from decimal. 

,REASON = reason code 

specifies the reason code that the user wants to pass to subsequent recovery exits. The 
value range for the reason code is a 32-bit hexadecimal number or a 31 -bit decimal 
number. This reason code supplements the completion code associated with an abnormal 
termination, allowing the user to uniquely identify the cause of the abnormal termination. 
The recovery termination manager propagates the reason code to each recovery exit and 
to the TCB and ASCB control blocks, making it available for system messages. 

,DUMP 
„STEP 

,„code type 
,DUMP,STEP 
,DUMP„C0*fe type 
„STEP,co<fe type 
,DUMP,STEP,code type 

specifies options available with the ABEND macro instruction: 

DUMP specifies that a dump is requested of virtual storage areas assigned to the task and 
control blocks pertaining to the task. A separate dump is provided for each of the tasks 
being terminated as a result of ABEND. If a //SYSABEND, //SYSMDUMP, or 
//SYSUDUMP DD statement is not provided, the DUMP parameter is ignored. 

STEP specifies that the entire job step of the active task is to be abnormally terminated. 

Note: If the STEP parameter is coded in an ABEND macro under TSO, the TSO job 
will be terminated. 

code type specifies that the completion code is to be treated as a USER or SYSTEM code. 

,DUMPOPT =parm list addr 

specifies the address of a parameter list valid for the SNAP macro instruction. The 
parameter list is used to produce a tailored dump, and may be created by using the list 
form of the SNAP macro instruction, or a compatible list may be created. The TCB, 
DCB, ID, and STRHDR options available on SNAP will be ignored if they appear in the 
parameter list; the TCB used will be that of the task being terminated, the DCB used will 
be provided by the ABDUMP routine. If a //SYSABEND, //SYSMDUMP, or 
//SYSUDUMP DD statement is not provided, the DUMPOPT parameter is ignored. 

If the dump options specified include ranges of storage areas to be dumped, only the 
storage areas in the first thirty ranges will be dumped. If SUBPLST is specified in the 
SNAP parameter list passed to the ABEND macro instruction via DUMPOPT, the first 
seven subpools will be dumped. 
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Example 1 

Operation: Terminate with a user completion code of 432. 

ABEND 432 

Example 2 

Operation: Terminate with the user completion code that is contained in register 5. The entire 
job step is to be terminated. 

ABEND ( 5 ) , , STEP 

Example 3 

Operation: Terminate with a system completion code of X'0C4'. 

ABEND X * 0C4 ' , , , SYSTEM 
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ATTACH — Create a New Task 

This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. If your program is to execute in 31 -bit addressing mode, you must use the 
MVS/XA version of this macro instruction. Except for the address of the DCB, all input 
parameters to the ATTACH macro instruction can have addresses greater than 16 Mb if the 
issuer is executing in 31 -bit addressing mode. 

The ATTACH macro instruction causes the control program to create a new task and indicates 
the entry point in the program to be given control when the new task becomes active. The 
entry point name that is specified must be a member name or an alias in a directory of a 
partitioned data set, or must have been specified in an IDENTIFY macro instruction. If the 
specified entry point cannot be located, the new subtask is abnormally terminated. 

On entry to the attached routine, the high-order bit, bit 0, of register 14 is set to indicate the 
addressing mode of the issuer of the ATTACH macro. If bit is 0, the issuer is executing in 
24-bit addressing mode; if bit is 1, the issuer is executing in 31 -bit addressing mode. 

The address of the task control block for the new task is returned in register 1. The new task is 
a subtask of the originating task; the originating task is the task that was active when the 
ATTACH macro instruction was issued. The limit and dispatching priorities of the new task 
are the same as those of the originating task unless modified in the ATTACH macro 
instruction. 

The load module containing the program to be given control is brought into virtual storage if a 
usable copy is not available in virtual storage. The issuing program can provide an event 
control block, in which termination of the new task is posted, an exit routine to be given 
control when the new task is terminated, and a parameter list whose address is passed in 
register 1 to the new task. If the ECB or ETXR parameter is coded, a DETACH macro 
instruction must be issued to remove the subtask from the system before the program that 
issued the ATTACH macro instruction terminates. If the ECB or ETXR parameter is not 
coded, the subtask is automatically removed from the system upon completion of its execution. 
If the ECB parameter is specified in the ATTACH macro instruction, the ECB must be in 
storage so that the issuer of the attach can wait on it (using the WAIT macro instruction) and 
the control program can post it on behalf of the terminating task. The ATTACH macro 
instruction can also be used to specify that ownership of virtual subpools is to be assigned to 
the new task, or that the subpools are to be shared by the originating task and the new task. 
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The standard form of the ATTACH macro instruction is written as follows: 



ATTACH 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ATTACH. 

One or more blanks must follow ATTACH. 



EP — entry name 

EPLOC = entry name addr 

DE = list entry addr 

,DCB = deb addr 

,LPMOD = limit prior nmbr 

,DPMOD = disp prior nmbr 

,PARAM = (<«tar) 
,PARAM = (addr),VL = 1 

,ECB = ecb addr 

,ETXR = exit rtn addr 

,GSPV = subpool nmbr 
,GSPL =subpool list addr 

,SHSPV = subpool nmbr 
,SHSPL = subpool list addr 

,SZERO = YES 
,SZERO = NO 

,TASKLIB = deb addr 

,STAI = (exit addr) 

,STAI = (exit addr, par m addr) 

,ESTAI = (exit addr) 

,ESTAI = (exit addrparm addr) 

.PURGE = QUIESCE 
,PURGE = NONE 
,PURGE = HALT 

ASYNCH = NO 
ASYNCH = YES 

,TERM = NO 
,TERM = YES 

.RELATED = value 



entry name: symbol. 

entry name addr: A-type address, or register (2) - (12). 

list entry addr: A-type address, or register (2) - (12). 

deb addr: A-type address, or register (2) - (12). 

limit prior nmbr: symbol, decimal digit, or register (2) - (12). 

disp prior nmbr: symbol, decimal digit, or register (2) - (12). 

addr: A-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 

PARAM = (addr, addr, addr) 

ecb addr: A-type address, or register (2) - (12). 

exit rtn addr: A-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit, or register (2) - (12). 
subpool list addr: A-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit, or register (2)-(12). 
subpool list addr: A-type address, or register (2)-(12). 

Default: SZERO = YES 

deb addr: A-type address, or register (2)-(12). 

exit addr: A-type address, or register (2)-(12). 
parm addr: A-type address, or register (2)-(12). 



Note: PURGE may be specified only if STAI or ESTAI is specified. 
Default for STAI: PURGE = QUIESCE 
Default for ESTAI: PURGE = NONE 

Note: ASYNCH may be specified only if STAI or ESTAI is specified. 
Default for STAI: ASYNCH = NO 
Default for ESTAI: ASYNCH = YES 

Note: TERM may be specified only if ESTAI is specified. 
Default: TERM = NO 



value: any valid macro keyword specification. 



The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

specifies the entry name, the address of the entry name, or the address of the name field 
of a 60-byte list entry for the entry name that was constructed using the BLDL macro 
instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. 



Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

If an unauthorized program issues the ATTACH macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
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ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the ATTACH. 
The DE information supplied by an unauthorized program will also be ignored if the 
ATTACH macro instruction is requesting access to a program or library that is controlled 
by the System Authorization Facility. 

,VCB = deb addr 

specifies the address of the data control block for the partitioned data set containing the 
entry name described above. (Note: The DCB must be opened before the ATTACH 
macro instruction is executed and must be the DCB used in the BLDL that built the 60 
byte DE list entry. The DCB must remain open until the subtask becomes active, and it 
should not be closed immediately following the attach macro.) 

Note: DCB must reside in 24-bit addressable storage. 

,LPMOD = limit prior nmbr 

specifies the number (255 or less) to be subtracted from the current limit priority of the 
originating task. The result is the limit priority of the new task. If this parameter is 
omitted, the current limit priority of the originating task is assigned as the limit priority of 
the new task. 

,DPMOD = disp prior nmbr 

specifies the signed number (255 or less) to be algebraically added to the current 
dispatching priority of the originating task. The result is assigned as the dispatching 
priority of the new task, unless it is greater than the limit priority of the new task. If the 
result is greater, the limit priority is assigned as the dispatching priority. 

If a register is designated, a negative number must be in two's complement form in the 
register. If this parameter is omitted, the dispatching priority assigned is the smaller of 
either the new task's limit priority or the originating task's dispatching priority. 

,P ARAM = (addr) 

,PARAM = (addr\YL = 1 

specifies address(es) to be passed to the control program. Each address is expanded inline 
to a fullword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first word when the program is given control. 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL= 1 causes the high-order bit of the last address to be set to 1; the bit 
can be checked to find the end of the list. 

,ECB = ecb addr 

specifies the address of an event control block for the new task to be used by the control 
program to indicate the termination of the new task. The ECB must be in storage so that 
the issuer of the attach can wait on it (using the WAIT macro instruction) and the control 
program can post it on behalf of the terminating task. The return code (if the task is 
terminated normally) or the completion code (if the task is terminated abnormally) is also 
placed in the event control block. If this parameter is coded, a DETACH macro 
instruction must be issued to remove the subtask from the system after the subtask has 
been terminated. 

,ETXR = exit rtn addr 

specifies the address of the end-of-task exit routine to be given control after the new task 
is normally or abnormally terminated. The exit routine is given control when the 
originating task becomes active after the subtask is terminated, and must be in virtual 
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storage when required. If this parameter is coded, a DETACH macro instruction must be 
issued to remove the subtask from the system after the subtask has been terminated. 

The exit routine receives control in the addressing mode of the issuer of the ATTACH 
macro instruction. ATTACH processing issues an ABEND with completion code X'72A' 
if a task attempts to create two subtasks with the same exit routine in different addressing 
modes. 

The contents of the registers when the exit routine is given control are as follows: 

Register Contents 

Control program information. 

1 Address of the task control block for the task that was terminated. 
2-12 Unpredictable. 

13 Address of a save area provided by the control program. 

14 Return address (to the control program). 

15 Address of the exit routine. 

The exit routine is responsible for saving and restoring the registers. 

,GSPV = subpool nmbr 

,GSPL = subpool list addr 

specifies a virtual storage subpool number less than 128 or the address of a list of 
virtual storage subpool numbers each less than 128. Except for subpool zero, 
ownership of each of the specified subpools is assigned to the new task. Although it 
can be specified, subpool zero cannot be transferred. When ownership of a subpool is 
transferred, programs of the originating task can no longer GETMAIN or FREEMAIN 
the associated virtual storage areas. 

If GSPL is specified, the first byte of the list contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage subpool number. 

,SHSPV = subpool nmbr 

,SHSPL = subpool list addr 

specifies a virtual storage subpool number less than 128 or the address of a list of virtual 
storage subpool numbers each less than 128. Programs of both originating task and the 
new task can use the associated virtual storage areas. 

If SHSPL is specified, the first byte of the list contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage subpool number. 

,SZERO = YES 
,SZERO = NO 

specifies whether subpool is to be shared with the subtask. YES specifies that subpool 
is to be shared; NO specifies that subpool is not to be shared. 

,TASKLIB = deb addr 

specifies that a task library DCB address has been supplied and is stored in TCBJLB. 
Otherwise, TCBJLB is propagated from the originating task. (Note: The DCB must be 
opened before the ATTACH macro instruction is executed.) SYS1.LINKLIB is the last 
library searched. If the DCB address specifies SYS1.LINKLIB, the search begins with 
SYS1.LINKLIB, goes through other libraries, and ends with SYS1.LINKLIB. An 806-4 
abend might occur if the requested module is in another library. 

Note: DCB must reside in 24-bit addressable storage. 
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,STAI = (exit addr) 

,STAI = (exit addr.parm addr) 

,ESTAI = (exit addr) 

,ESTAI = (exit addr.parm addr) 

specifies whether a STAI or ESTAI SCB is to be created; any STAI/ESTAI SCBs queued 

to the originating task are propagated to the new task. 

The exit addr specifies the address of the STAI or ESTAI exit routine which is to receive 
control if the subtask abnormally terminates; the exit routine must be in virtual storage at 
the time of abnormal termination. The parm addr is the address of a parameter list which 
may be used by the STAI or ESTAI exit routine. 

ATTACH processing passes control to an ESTAI exit routine in the addressing mode of 
the issuer of the ATTACH macro instruction. Therefore, the ESTAI exit routine can 
execute in either 24-bit or 31 -bit addressing mode. A STAI exit routine can execute only 
in 24-bit addressing mode. If a caller in 31 -bit addressing mode specifies the STAI 
parameter on the ATTACH macro instruction, the caller is abended with an X'52A' 
completion code. 

,PURGE = QUIESCE 
,PURGE = NONE 
,PURGE = HALT 

specifies what action is to be taken with regard to I/O operations when the subtask is 
abnormally terminated. No action may be specified (NONE), a halting of I/O operations 
may be requested (HALT), or a quiescing of I/O operations may be indicated 
(QUIESCE). 

,ASYNCH = NO 
,ASYNCH = YES 

specifies whether asynchronous exits are to be allowed when a subtask abnormal 
termination occurs. 

ASYNCH = YES must be coded if: 

• Any supervisor services that require asynchronous interruptions to complete their 
normal processing are going to be requested by the ESTAE exit routine. 

• PURGE = QUIESCE is specified for any access method that requires asynchronous 
interruptions to complete normal input/output processing. 

• PURGE = NONE is specified and the CHECK macro instruction is issued in the 
ESTAE exit routine for any access method that requires asynchronous interruptions 
to complete normal input/output processing. 

Note: If ASYNCH = YES is specified and the ABEND was originally scheduled because 
of an error in asynchronous exit handling, an ABEND recursion will develop when an 
asynchronous exit handling was the cause of the failure. 



) 
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,TERM = NO 
,TERM=YES 

specifies whether the exit routine associated with the ESTAI request is also to be 
scheduled in the following situations: 

• CANCEL 

• Forced LOGOFF 

• Job step timer expiration 

• Wait time limit for job step exceeded 

• ABEND condition because incomplete task detached when STAE option not specified 
on DETACH 

• ATTACH macro instruction with the ESTAI operand issued by subtask and attaching 
task abnormally terminates 

.RELATED rvalue 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

ATTCH1 ATTACH EP=MY JOB , ECB=MYECB ,RELATED= (DETCH1 , 

•CREATE SUBTASK' ) 



DETCH1 DETACH ( 1) ,RELATED= (ATTCH1 ,' DETACH SUBTASK' ) 

Note: The ATTACH macro instruction will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 1 5 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Successful completion. 

04 ATTACH was issued in a STAE exit; processing not completed. 

08 Insufficient storage available for control block for STAI/ESTAI request; processing not completed. 

0C Invalid exit routine address or invalid parameter list address specified with STAI parameter; processing 

not completed. 

Note: For any return code other than 00, register 1 is set to zero upon return. 
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Example 1 



Example 2 



Note: The program manager processing for ATTACH is performed under the new subtask, 
after control has been returned to the originating task. Therefore, it is possible for the 
originating task to obtain return code 00, and still not have the subtask successfully created (for 
example, if the entry name could not be found by the program manager). In such cases, the 
new subtask is abnormally terminated. 



Operation: Cause the program named in the list to be attached. Establish RTN as an end of 
task exit routine. 

ATTACH DE=LISTNAME,ETXR=RTN 



Operation: Cause PROGRAM 1 to be attached, share subpool 5, wait on WORD1 to 
synchronize processing with that of the subtask, and establish EXIT1 as an ESTAI exit. 

ATTACH EP=PR0GRAM1 , SHSPV=5 , ECB=WORDl , ESTAE= ( EXIT1 ) 



) 



mr 
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ATTACH (List Form) 



Two parameter lists are used in an ATTACH macro instruction: a control program parameter 
list and an optional problem program parameter list. You can construct only the control 
program parameter list in the list form of ATTACH. Address parameters to be passed in a 
parameter list to the problem program can be provided using the list form of the CALL macro 
instruction. This parameter list can be referred to in the execute form of ATTACH. 

The list form of the ATTACH macro instruction is written as follows: 



name 
b 

ATTACH 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ATTACH. 

One or more blanks must follow ATTACH. 



EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 

,DCB = deb addr 

,LPMOD = limit prior nmbr 

,DPMOD = disp prior nmbr 

,ECB = ecb addr 

,ETXR = exit rtn addr 

,GSPV = subpool nmbr 
,GSPL=subpool list addr 

,SHSPV = subpool nmbr 
,SHSPL = subpool list addr 

,SZERO = YES 
,SZERO = NO 

,TASKLIB = deb addr 

,STAI = (exit addr) 

,STAI = (exit addr,parm addr) 

,ESTAI = (exit addr) 

,PURGE = QUIESCE 
.PURGE = NONE 
.PURGE = HALT 

,ASYNCH = NO 
.ASYNCH = YES 

/TERM = NO 
/TERM = YES 

.RELATED = w*/we 

,SF = L 



entry name: symbol. 

entry name addr: A-type address. 

list entry addr: A-type address. 

deb addr: A-type address. 

limit prior nmbr: symbol or decimal digit. 

disp prior nmbr: symbol or decimal digit. 

ecb addr: A-type address. 

exit rtn addr: A-type address. 

subpool nmbr: symbol or decimal digit. 
subpool list addr: A-type address. 

subpool nmbr: symbol or decimal digit. 
subpool list addr: A-type address. 

Default: SZERO = YES 

deb addr: A-type address. 

exit addr: A-type address. 
parm addr: A-type address. 



Note: PURGE may be specified only if STAI or ESTAI is specified. 
Default for STAI: PURGE = QUIESCE 
Default for ESTAI: PURGE = NONE 

Note: ASYNCH may be specified only if STAI or ESTAI is specified. 
Default for STAI: ASYNCH = NO 
Default for ESTAI: ASYNCH = YES 

Note: TERM may be specified only if ESTAI is specified. 
Default: TERM = NO 

value: any valid macro keyword specification. 



The parameters are explained under the standard form of the ATTACH macro instruction, with 
the following exception: 



,SF = L 

specifies the list form of the ATTACH macro instruction. 



( 
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ATTACH (Execute Form) 



Two parameter lists are used in ATTACH: a control program parameter list and an optional 
problem program parameter list. Either or both of these parameter lists can be remote and can 
be referred to and modified by the execute form of ATTACH. If only the problem program 
parameter list is remote, parameters that require use of the control program parameter list 
cause that list to be constructed inline as part of the macro expansion. 

The execute form of the ATTACH macro instruction is written as follows: 



) 



name 
b 

ATTACH 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ATTACH. 

One or more blanks must follow ATTACH. 



) 



EP = entry name 
EPLOC = entry name addr 
DE = list entry addr 

,DCB = deb addr 

,LPMOD = limit prior nmbr 

,DPMOD = disp prior nmbr 

,PARAM = (addr) 
,PARAM = (<K#r),VL = l 

,ECB = ecb addr 

,ETXR = exit rtn addr 

,GSPV = subpool nmbr 
,GSPL= subpool list addr 

,SHSPV = subpool nmbr 
,SHSPL= subpool list addr 

,SZERO = YES 
,SZERO = NO 

,TASKLIB = deb addr 

,STAI = (exit addr) 

,STAI = (exit addr,parm addr) 

,ESTAI = (exit addr) 

,ESTAI = (exit addr,parm addr) 

,PURGE = QUIESCE 
.PURGE = NONE 
,PURGE = HALT 

,ASYNCH = NO 
,ASYNCH = YES 

/TERM = NO 
/TERM = YES 

,RELATED = va/we 

,MF = (E,prob addr) 

,SF = (E,ctrladdr) 

,MF = (E,prob addr),S¥ = (E,ctrl addr) 



entry name: symbol. 

entry name addr: RX-type address, or register (2) - (12). 

list entry addr: RX-type address, or register (2) - (12). 

deb addr: RX-type address, or register (2) - (12). 

limit prior nmbr: symbol, decimal digit, or register (2) - (12). 

disp prior nmbr: symbol, decimal digit, or register (2) - (12). 

addr: RX-type address, or register (2) - (12). 

Note: addr is one or more addresses, separated by commas. For example, 

PARAM = (addr, addr, addr) 

ecb addr: RX-type address, or register (2) - (12) . 

exit rtn addr: RX-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit, or register (2) - (12). 
subpool list addr: RX-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit, or register (2) - (12). 
subpool list addr: RX-type address, or register (2) - (12). 



deb addr: RX-type address, or register (2) - (12). 

exit addr: RX-type address, or register (2) - (12). 
parm addr: RX-type address, or register (2) - (12). 



Note: PURGE may be specified only if STAI or ESTAI is specified. 

Note: ASYNCH may be specified only if STAI or ESTAI is specified. 
Note: TERM may be specified only if ESTAI is specified. 

value: any valid macro keyword specification. 

prob addr: RX-type address, or register (1) or (2) - {12). 
Ctrl addr: RX-type address, or register (2) - (12) or (15). 
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The parameters are explained under the standard form of the ATTACH macro instruction, with 
the following exceptions: 

9 MF = (E i probaddr) 

,SF = (E,c*r/a<fc/r) 

,MF = (E,prob addr),SE = (E,ctrl addr) 

specifies the execute form of the ATTACH macro instruction using either a remote 
problem program parameter list or a remote control program parameter list. Any 
problem program or control program parameters are provided in parameter lists expanded 
inline. 

Notes: 

1. If STAI is specified on the execute form, the following fields are overlaid in the control 
program parameter list: exit addr, parm addr, PURGE, and ASYNCH. Ifparm addr is not 
specified, zero is used; if PURGE or ASYNCH are not specified, defaults are used. 

2. If ESTAI is specified on the execute form, then the following fields are overlaid: exit addr, 
parm addr, PURGE, ASYNCH, and TERM. Ifparm addr is not specified, zero is used; if 
PURGE, ASYNCH, or TERM are not specified, defaults are used. 

3. If the STAI or ESTAI is to be specified, it must be completely specified on either the list or 
execute form, but not on both forms. 

4. If SZERO is not specified on the list or execute form, the default is SZERO = YES. If 
SZERO = NO is specified on either the list form or a previous execute form using the same 
SF=list, then SZERO = YES is ignored for any following execute forms of the macro. Once 
SZERO = NO is specified, it is in effect for all users of that list. 



i 
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CALL — Pass Control to a Control Section 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. You cannot use the CALL macro instruction to pass control to a 
program in a different addressing mode. 

The CALL macro instruction passes control to a control section at a specified entry point as 
follows: 

• OVERLAY: The overlay segment containing the designated entry point is brought into 
virtual storage if required, and control is passed to the segment. 

Refer to Linkage Editor and Loader for details on overlay. The CALL macro instruction 
cannot be used in an asynchronous exit routine. 

• NON-OVERLAY: If a symbol is designated, the linkage editor includes the load module 
containing that entry point in the same load module containing the CALL instruction. 
When the CALL macro instruction is executed, control is passed to the control section at 
the specified entry point. 

The linkage relationship established when control is passed is the same as that created by a 
BAL instruction; that is, the issuing program expects control to be returned. The control 
program is not involved in passing control, so the reusability of the called program must be 
maintained by the user. 

An address parameter list can be constructed and a calling sequence identifier can be provided. 

The standard form of the CALL macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede CALL. 
CALL 

b One or more blanks must follow CALL. 

entry name entry name: symbol or register (15). 

,(addr) addr: A-type address, or register (2) - (12). 

,{addr),VL Note: addr is one or more addresses, separated by commas. For example, 

{addr , addr , addr) 

,ID = id nmbr id nmbr: symbol or decimal digit, with a maximum value of 4095. 

The parameters are explained as follows: 
entry name 



3 



name 

specifies the entry name to be given control. 



,(addr) 

,(addr%XL 

specifies address(es) to be passed to the control program. Each address is expanded inline 
to a fullword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. (If this parameter is not 
coded, register 1 is not altered.) 
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Example 1 



VL should be coded only if the called program can be passed a variable number of 
parameters. VL causes the high-order bit of the last address parameter to be set to 1; the 
bit can be checked to find the end of the list. 

■JD — idnmbr 

specifies an identifier useful for debugging purposes only. The last fullword of the macro 
expansion is a NOP instruction containing the identifier value in bytes 3 and 4. 

Upon entry to the called program, the register contents are as follows: 

Register Meaning 

1 Address of parameter list, if present. 

14 Return address. 

15 Entry address of called program. 



Operation: Call the entry point contained in register 15, and pass three addresses to the control 
program. 

CALL ( 15) , (ADDR1,ADDR2 , ADDR3 ) 



( 
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CALL (List Form) 



) 



The list form of the CALL macro instruction is used to construct a nonexecutable problem 
program parameter list. This list form generates only ADCONs of the address parameters. 
This problem program parameter list can be referred to in the execute form of a CALL, LINK, 
ATTACH, or XCTL macro instruction. 

The list form of the CALL macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede CALL. 
CALL 

b One or more blanks must follow CALL. 

,(addr) addr: A-type address. 

,(addr),VL Note: addr is one or more addresses, separated by commas. For example, 

(addr, addr, addr) 

,MF = L 



The parameters are explained under the standard form of the CALL macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the CALL macro instruction. 
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CALL (Execute Form) 



A remote problem program parameter list is referred to and can be modified by the execute 
form of the CALL macro instruction. Only executable instructions and a VCON of the entry 
point are generated. 

The execute form of the CALL macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede CALL. 
CALL 

b One or more blanks must follow CALL. 

entry name entry name: symbol or register (15). 

,(addr) addr: RX-type address, or register (2) - (12). 

,(addr),VL Note: addr is one or more addresses, separated by commas. For example, 

(addr, addr, addr) 

,ID = id nmbr id nmbr: symbol or decimal digit, with a maximum value of 4095. 

,MF = (E,pro6 addr) prob addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the CALL macro instruction, with the 
following exception: 

,MF = (E,probaddr) 

specifies the execute form of the CALL macro instruction. This form uses a remote 
problem program parameter list. If the address parameters are also specified in this form, 
the ADCONS of the parameter are placed on contiguous fullword boundaries beginning 
at the address specified in the MF parameter, and sequentially overlaying corresponding 
fullwords in the existing list. 



( 
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CHAP — Change Dispatching Priority 



) 







CHAP changes the dispatching priority of the task or any of its subtasks relative to the other 
tasks in the address space. It does not change the priority relative to other tasks in the system. 
CHAP may also change the limit priority of a subtask. (See the section "Priorities" in this 
publication.) The algebraic sum of the priority value and the dispatching priority of the subject 
task determines the new dispatching priority. 

• If the subject task is the task executing CHAP, its dispatching priority is set equal to the 
sum of the priority value and the dispatching priority. This value is not set at less than 
zero or greater than the limit priority for the task. Its limit priority is unaffected. 

• If the subject task is a subtask of the task executing CHAP, its dispatching priority is set 
equal to the sum of the priority value and the dispatching priority. This value is not set at 
less than zero or greater than the limit priority of the task executing CHAP. After this 
modification, if the subtask's dispatching priority exceeds its limit priority, the limit priority 
is made equal to the dispatching priority. 

The CHAP macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede CHAP. 
CHAP 

b One or more blanks must follow CHAP. 

priority value priority value: symbol, decimal digit, or register (0) or (2) - (12). 

,'S' tcb addr: RX-type address, or register (1) or (2) - (12). 

,tcb addr Default: 'S' 

.RELATED = value value: any valid macro keyword specification. 



The parameters are explained as follows: 

priority value 

specifies the signed value to be added to the dispatching priority of the specified task. If 
the value is negative and contained in a register, it must be in two's complement form. 

,'S' 

,tcb addr 

specifies the address of a fullword on a fullword boundary containing the address of a 
task control block (TCB) for a subtask of the active task. If 'S' is coded or assumed, the 
dispatching priority of the active task is updated. 

Note: TCB must reside in 24-bit addressable storage. 

,RELATED = value 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user and may be any valid coding values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
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LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

CHAPUP CHAP 1 , ' S ' , RELATED= ( CHAPDOWN , ' UP PRIORITY ' ) 



CHAPDOWN CHAP - 1 , ' S ' , RELATED= ( CHAPUP , 
1 RESUME INITIAL PRIORITY ' ) 

Note: The second CHAP macro instruction will fit on one line when coded, so there is 
no need for a continuation indicator. 



Example 1 



Operation: Lower by 2 the dispatching priority of the subtask TCB, whose address is in a 
fullword which is addressed by register 1. The subtask TCB will be repositioned on the 
dispatching queue in accordance with its new dispatching priority. 



CHAP 



-2,(1) 



Example 2 



Operation: Cause the TCB of the task issuing CHAP to be repositioned at the bottom of the 
group of TCBs on the dispatching queue for the address space, having the same dispatching 
priority as that task. 

CHAP 



I 



< 
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CPOOL — Perform Cell Pool Services 

The CPOOL macro instruction creates a cell pool, obtains or returns a cell to the cell pool, or 
deletes the previously built cell pool, according to the function requested. Problem state, 
non-system key users cannot create cell pools in subpools greater than 127. On entry to the 
CPOOL macro instruction, users who specify the parameters: BUILD, DELETE, or 
REGS = SAVE must pass the address of a 72-byte save area in register 13. 

The CPOOL macro instruction is written as follows: 



name 
b 
CPOOL 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede CPOOL. 

One or more blanks must follow CPOOL. 



) 



BUILD 
GET 
FREE 
DELETE 

,UNCOND 
,U 

,COND 
,C 

,PCELLCT = primary cell count 

,SCELLCT = secondary cell count 

,CSIZE = cell size 

,SP = subpool number 



Default: UNCOND 

Note: This parameter can be specified only with the GET keyword. 



cell count: symbol, decimal digit, or register (0), (2) - (12). 

Note: This parameter can be specified only with the BUILD keyword. 

Default: PCELLCT 

Note: This parameter can be specified only with the BUILD keyword. 

cell size: symbol, decimal digit, or register (0), (2) - (12). 

Note: This parameter can be specified only with the BUILD keyword. 

subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Note: This parameter can be specified only with the BUILD keyword. 
Default: SP = 



\ 



,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

,CPID= pool id 



,CELL = cell addr 



,HDR = hdr 



,REGS=SAVE 
,REGS = USE 



Default: LOC = RES 

Note: This parameter can be specified only with the BUILD keyword. 



pool id: RX-type address or register (0), (2) - (12). 

Note: This parameter must be specified with the GET, FREE, and DELETE 

keywords but is optional with the BUILD keyword. 

cell addr: RX-type address or register (2) - (12). 

Note: This parameter is required with the FREE keyword, is optional with the 

GET keyword, and cannot be specified with the BUILD and DELETE 

keywords. 

hdr: character string enclosed in single quotes, RX-type address, or register 

(0),(2)-(12). 

Default: 'CPOOL CELL POOL' 

Note: This parameter can be specified only with the BUILD keyword. 

Default: REGS = SAVE 

Note: This parameter can be specified only with the GET or FREE keywords. 
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The parameters are explained as follows: 

BUILD 
GET 
FREE 
DELETE 

specifies the cell pool service to be performed. 

BUILD creates a cell pool in a specified subpool by allocating storage and chaining the 
cells together. It returns an identifier (CPID) to be used with GET, FREE, and DELETE 
requests. Therefore, BUILD must be done before GET, FREE, or DELETE. 

GET attempts to obtain a cell from the previously built cell pool. This request can be 
conditional or unconditional as described under the UNCOND/COND keyword. 

FREE returns a cell to the cell pool. 

DELETE deletes a previously built cell pool and frees storage for the initial extent, all 
secondary extents, and all pool control blocks. 

,UNCOND 
,U 

,COND 
,C 

when used with GET specifies whether the request for a cell is conditional or 
unconditional. If COND or C is specified and the cell pool is empty, the CPOOL service 
routine returns to the caller without a cell and places a zero in the return field of the cell 
address. If UNCOND or U is specified and the cell pool is empty, the CPOOL service 
routine extends the pool in order to obtain a cell for the caller. 

,PCELLCT —primary cell count 

specifies the number of cells expected to be needed in the initial extent of the cell pool. 
The CPOOL service module uses PCELLCT and cell size, (CSIZE) to determine the 
optimum number of cells to provide in order to make effective use of virtual and real 
storage. 

,SCELLCT = secondary cell count 

specifies the number of cells expected to be in each secondary or non-initial extent of the 
cell pool. The CPOOL service routine uses SCELLCT and CSIZE to determine the 
optimum number of cells to provide in order to make effective use of virtual and real 
storage. 

,CSIZE = cell size 

specifies the number of bytes in each cell of the cell pool. If CSIZE is a multiple of 8, the 
cell resides on doubleword boundaries. If CSIZE is a multiple of 4, the cell resides on 
word boundaries. The minimum value of CSIZE is 4 bytes. 

,SP = subpool number 

specifies the subpool from which the cell pool is to be obtained. If a register or variable is 
specified, the subpool number is taken from bits 24-31. 



I 
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) 



,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

specifies the location of virtual storage and real storage for the cell pool. 

Note: The location of real storage using this parameter is only guaranteed after the 
storage is fixed. 

LOC = BELOW indicates that virtual and real storage are to be allocated below 16 Mb. 

LOC = (BELOW, ANY) indicates that virtual storage is to be allocated below 16 Mb and 
real storage can be anywhere. 

LOC = ANY and LOC = (ANY, ANY) indicate that both virtual and real storage can be 
located anywhere. 

LOC = RES indicates that the location of virtual and real storage depends on the location 
of the issuer of the macro. If the issuer resides below 16 Mb, virtual and real storage are 
allocated below 16 Mb; if the issuer resides above 16 Mb, virtual and real storage can be 
located anywhere. 

LOC = (RES, ANY) indicates that the location of virtual storage depends on the location 
of the issuer of the macro. If the issuer resides below 16 Mb, virtual storage is allocated 
below 16 Mb; if the issuer resides above 16 Mb, virtual storage is allocated anywhere. 
Real storage can be located anywhere. 

Note: Callers executing in 24-bit addressing mode could perform BUILD request services 
for cell pools located in storage above 16 Mb by specifying LOC = ANY or 

LOC = (ANY,ANY). 

,CFID=poolid 

specifies the address or register containing the cell pool identifier that is returned to the 
caller after the pool is created using CPOOL BUILD. The issuer must specify CPID on 
all subsequent CPOOL requests containing the keywords GET, FREE, or DELETE. 

,CELL = cell addr 

specifies the address or register where the cell address is returned to the caller on a GET 
or FREE request. 

,HDR = Mr 

specifies a 24-byte header, which is placed in the header of each initial and secondary 
extent. The header can contain user-supplied information that would be useful in a 
dump. 

,REGS = SAVE 
,REGS = USE 

indicates whether or not registers 2-12 are to be saved. If REGS = SAVE is specified, the 
registers are saved in a 72-byte user-supplied save area pointed to by register 13. If 
REGS = USE is specified, the registers are not saved. 
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Example 1 



Example 2 



Example 3 



Example 4 



The contents of the registers on return from this macro depends on the parameters specified. 

Registers) Comment 

Contains the cell pool identification (CPID) 

1 Contains the address of the cell that was obtained if GET was specified; contains zero if GET conditional 
was specified and the cell could not be obtained 

2-12 Saved for BUILD and DELETE requests or if REGS = SAVE is specified 

5-13 Saved if GET conditional or FREE is specified with REGS = USE 

1 3 Saved if GET unconditional and REGS = USE, BUILD, or DELETE is specified 



Operation: Create a cell pool containing 40-byte cells from subpool 2. Allow for 10 cells in the 
initial extent and 20 cells in all subsequent extents of the cell pool. 

CPOOL BUILD , PCELLCT=10 , SCELLCT=20 , CSIZE=40 , SP=2 



Operation: Unconditionally obtain a cell pool, specifying the pool ID in register 2. Do not 
save the registers. 

CPOOL GET , U , CPID= ( 2 ) , REGS=USE 



Operation: Free a cell specifying the pool ID in register 2 and the cell address in register 3. 

CPOOL FREE , CPID= ( 2 ) , CELL= ( 3 ) 

Operation: Delete a cell pool, specifying the pool ID in register 2. 

CPOOL DELETE, CPID= (2) 



< 
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CPOOL - (List Form) 



The list form of the CPOOL macro instruction builds a non-executable parameter list that can 
be referred to by the execute form of the CPOOL macro. 

The list form of the CPOOL macro instruction is written as follows: 



name 
b 
CPOOL 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede CPOOL. 

One or more blanks must follow CPOOL. 



BUILD 

,PCELLCT = primary cell count 



cell count: symbol, decimal digit, or register (0), (2) - (12). 

Note: PCELLCT must be specified on either the list or the execute form of the 

macro. 



,SCELLCT = secondary cell count Default: PCELLCT 
,CSIZE = cell size cell size: symbol, decimal digit, or register (0), (2) - (12). 



,SP = subpool number 



Note: CSIZE must be specified on either the list or the execute form of the 
macro. 

subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Default: SP = 



) 



) 



,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

,CPID =pool id 
,HDR = Mr 



Default: LOC = RES 



pool id: A- type address or register (0), (2) - (12). 

hdr: character string enclosed in single quotes, A-type address, or register (0), 
(2) - (12). 



,MF = L 



The parameters are explained under the standard form of the CPOOL macro instruction with 
the following exception: 



,MF = L 

specifies the list form of the CPOOL instruction. 
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CPOOL — (Execute Form) 



The execute form of the CPOOL macro instruction is written as follows: 



name 
b 
CPOOL 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede CPOOL. 

One or more blanks must follow CPOOL. 



BUILD 

,PCELLCT = primary cell count 

,SCELLCT = secondary cell count 
,CSIZE = cell size 

,SP = subpool number 



cell count: symbol, decimal digit, or register (0), (2) - (12). 

Note: PCELLCT must be specified on either the list or the execute form of the 

macro. 

Default: PCELLCT 

cell size: symbol, decimal digit, or register (0), (2) - (12). 

Note: CSIZE must be specified on either the list or the execute form of the 

macro. 

subpool number: symbol, decimal digit 0-127, or register (0), (2) - (12). 
Default: SP = 



,LOC = BELOW 
,LOC = (BELOW,ANY) 
,LOC = ANY 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

,CPlD=poolid 
,HDR = hdr 

,MF = (E,ctrlprog) 



Default: LOC = RES 



pool id: RX-type address or register (0), (2) - (12). 

hdr: character string enclosed in single quotes, RX-type address, or register 
(0), (2) - (12). 

ctrl prog: RX-type address or register (0) - (12). 



The parameters are explained under the standard form of the CPOOL macro instruction with 
the following exception: 

,M$ = (E,ctrlprog) 

specifies the execute form of the CPOOL instruction. 



( 
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) 



CPUTIMER - Provide Current CPU Timer Value 

The CPUTIMER macro instruction provides the current CPU timer value for this processor. 
This value consists of the time remaining in a time interval established by the STIMER macro 
instruction. If there is no outstanding time interval, the value returned by the macro 
instruction is meaningless. 

The caller of the CPUTIMER macro instruction must provide the address of a 72-byte save 
area in register 13. 

The CPUTIMER macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 

b One or more blanks must precede CPUTIMER. 
CPUTIMER 

b One or more blanks must follow CPUTIMER. 

TV,stor addr Default: TU 

MIC,.stor addr stor addr: RX-type address, or register (1), (2) - (12). 

,ERRET = err rtn addr err rtn addr: RX-type address, or register (2) - (12). 

The parameters are explained as follows: 

TU 9 stor addr 
MIC,stor addr 

specifies the form in which the remaining time interval is to be returned to the caller. 

This value is returned as an unsigned 64-bit binary number, at the address specified by 

stor addr. stor addr must be the start of a double word area on a double word boundary 

and it must be a 31 -bit address. 

If TU is specified, the timer value is returned to the caller in timer units. The low-order 
bit of the timer value is approximately equal to 26.04166 microseconds (one timer unit). 

If MIC is specified, the timer value is returned to the caller in microseconds. Bit 51 of the 
timer value is equivalent to 1 microsecond. 

The resolution of CPU timer is model dependent. See Principles of Operation for a 
description of the CPU timer. 

,ERRET - err rtn addr 

specifies the 31 -bit address of the routine to be given control when the CPUTIMER 
function cannot be performed. If this parameter is omitted, the CPUTIMER function 
returns a code in general register 15 indicating why the function could not be performed. 
The error routine executes in the addressing mode of the issuer of the CPUTIMER macro 
instruction. 



|J0r 
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The return codes are as follows: 



Hexadecimal 
Code 



4 

8 

OC 

10 

14 



Meaning 

The function was performed. 

The function was not performed because the user-specified area was not on a double word boundary. 

The function was not performed because the user supplied an invalid address. 

The function was not performed because the value of the CPU timer was not usable. 

The function was not performed because a machine check occurred. 

The function was not performed because a program check occurred. 



Example 1 



Example 2 



Operation: Place the value of the CPU timer in microseconds in location TIMELEFT. 

CPUTIMER MIC, TIMELEFT 



Operation: Store the value of the CPU timer in time units in the location addressed by register 
1. 



Example 3 



Example 4 



CPUTIMER TU, (1) 



Operation: Store the value of the CPU timer in timer units in location TIMELEFT. If an 
error occurs, transfer control to the error routine labeled ERREXIT. 

CPUTIMER , TIMELEFT, ERRET=ERREXIT 



Operation: Place the value of the CPU timer in microseconds in the location addressed by 
register 1 . If an error occurs, transfer control to the address in register 2. 

CPUTIMER MIC , ( 1 ) , ERRET= ( 2 ) 



( 
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DELETE — Relinquish Control of a Load Module 



) 



The DELETE macro instruction cancels the effect of a previous LOAD macro instruction. If 
DELETE cancels the only outstanding LOAD request for the module and no other 
requirements exist for the module, the virtual storage occupied by the load module is released 
and is available for reassignment by the control program. 

The entry name specified in the DELETE macro instruction must be the same as that specified 
in the LOAD macro instruction that brought the load module into storage. Also, the DELETE 
macro instruction must be issued by the same task that issued the LOAD macro instruction. 

Any module loaded by a task will not be removed from virtual storage until the DELETE 
macro instruction is issued or end of task is reached. In addition, any module loaded by a 
system task will not be removed from virtual storage until a DELETE macro instruction is 
issued by a system task or end of task is reached. 

The DELETE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede DELETE. 
DELETE 

b One or more blanks must follow DELETE. 



EP = entry name entry name: symbol. 

EPLOC = entry name addr entry name addr: RX-type address, or register (0) or (2) - (12). 

)DE = /i« entry addr list entry addr: RX-type address, or register (0) or (2) - (12). 

,RELATED = value value: any valid macro keyword specification. 



The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

DE- list entry addr 

specifies the entry name, the address of the entry name, or the address of a 60-byte list 
entry for the entry name that was constructed using the BLDL macro instruction. If 
EPLOC is coded, the name must be padded to eight bytes, if necessary. 

,RELATED - value 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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Example 1 



The RELATED parameter may be used, for example, as follows: 

L0AD1 LOAD EP=APGIOHKl , RELATED= (DELI , 

1 LOAD APGIOHK1 ' ) 



DELI DELETE EP=APGIOHKl ,RELATED= (LOAD1, 

1 DELETE APGIOHK1 ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Successful completion of requested function. 

04 Request was not issued for this module, or attempt was made to delete a system module. 



Operation: Remove a module (PGMTOVLY) from virtual storage. 

DELETE EP=PGMTOVLY 



( 

1 54 Supervisor Services and Macro Instructions 



> 



) 



DEQ — Release a Serially Reusable Resource 

The DEQ macro instruction removes control of one or more serially reusable resources from 
the active task. Register 15 is set to if the request is satisfied. An unconditional request to 
release a resource from a task that is not in control of the resource, or a request that contains 
invalid parameters results in abnormal termination of the task. 

Note: When global resource serialization is active, the SYSTEM inclusion resource name list 
and the SYSTEMS exclusion resource name list are searched for every resource specified with a 
scope of SYSTEM or SYSTEMS. A resource whose name appears in one of these resource 
name lists might have its scope changed from the scope that appears on the macro instruction. 
See Planning: Global Resource Serialization for more information. 

The standard form of the DEQ macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede DEQ. 
DEQ 

b One or more blanks must follow DEQ. 

( 

qname addr qname addr: A-type address, or register (2) - (12). 

,rname addr rname addr: A-type address, or register (2) - 12). 

, rname length: symbol, decimal digit, or register (2) - (12). 

,rname length Note: rname length must be coded if a register is specified for rname addr. 

,STEP Default: STEP 

.SYSTEM 

,SYSTEMS 

) 

,RET = HAVE Default: RET = NONE 

,RET = NONE 

,RELATED = value value: any valid macro keyword specification. 

The parameters are explained as follows: 

( 

specifies the beginning of the resource(s) description. 

qname addr 

specifies the address in virtual storage of an 8-character name. The name can contain any 
valid hexadecimal digits. The qname must be the same name specified for the resource in 
an ENQ macro instruction. 

jname addr 

specifies the address in virtual storage of the name used in conjunction with qname and 
scope to represent the resource acquired by a previous ENQ macro instruction. The name 
can be qualified, must be from 1 to 255 bytes long, and can contain any valid 
hexadecimal digits. The rname must be the same name specified for the resource in an 
ENQ macro instruction. 
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,rname length 

specifies the length of the rname described above. The length must have the same value 
as specified in the previous ENQ macro instruction. If this parameter is omitted, the 
assembled length of the rname is used. You can specify a value between 1 and 255 to 
override the assembled length, or you may specify a value of 0. If is specified, the 
length of the rname must be contained in the first byte at the rname addr specified above. 



,STEP 

,SYSTEM 

,SYSTEMS 

specifies the scope of the resource. You must specify the same STEP, SYSTEM, or 
SYSTEMS option as you used in the ENQ macro instruction requesting the resource. 

) 

specifies the end of the resource(s) description. 

Note: The parameters qname addr, rname addr, rname length, and the scope can be 
repeated within a single set of parentheses to indicate multiple resources. These 
parameters can be repeated until there is a maximum of 255 characters including the 
parentheses. 

,RET=HAVE 
,RET = NONE 

specifies that the request for releasing the resources named in DEQ is to be conditional 
(HAVE) or unconditional (NONE). If this parameter is omitted, the request for release is 
unconditional, and the active task is abnormally terminated if it has not been assigned 
control of the resources. 

HAVE specifies that the request to release the resources named in the DEQ macro 
instruction is to be honored only if the active task has been assigned control of the 
resources. A return code is set if the resource is not held. 

NONE specifies an unconditional request to release the resources. The active task is 
abnormally terminated if it has not been assigned control of the resources. If the 
parameter is omitted, NONE is the default. 

,RELATED = ra/w<? 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and can be any valid coding values. 

< The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 



< 
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The RELATED parameter may be used, for example, as follows: 

ENQUEUE ENQ ( MAJOR , MINOR , S , 8 , STEP ) , 

RELATED= ( DEQUEUE , ■ OBTAIN RESOURCE ' ) 



DEQUEUE DEQ 



( MAJOR , MINOR , 8 , STEP ) , 

RELATED= (ENQUEUE , ' RELEASE RESOURCE ' ) 



Return codes are provided by the control program only if RET = HAVE is designated. If 
all of the return codes for the resources named in DEQ are 0, register 15 contains 0. If 
any of the return codes are not 0, register 15 contains the address of a virtual storage area 
containing the return codes as shown in Figure 50. The return codes are placed in the 
parameter list resulting from the macro expansion in the same sequence as the resource 
names in the DEQ macro instruction. The return codes are shown in Figure 51. 



Address 
Returned in 
Register 15 



Return 
Codes 



12 






24 



36 



12 



RC 1 



RC 2 






< ( 




Return codes are 
12 bytes apart, 
starting 3 bytes 
from the address 
in register 15. 



Figure 50. Return Code Area Used by DEQ 



) 
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Hexadecimal 

Code Meaning 



Example 1 



Example 2 



The .resource has been released. 

The resource has been requested for the task, but the task has not been assigned control. The task is 
not removed from the wait condition. (This return code could result if DEQ is issued within an exit 
routine which was given control because of an interruption.) 

Control of the resource has not been requested by the active task, or the resource has already been 
released. 



Figure 51. DEQ Macro Instruction Return Codes 



Operation: Release control of the resource in Example 1 of ENQ, (later in this section) if it has 
been assigned to the current task. The length of the rname is explicitly defined as 9 characters. 

DEQ ( MA JOR1, MINOR 1,9, STEP) ,RET=HAVE 



Operation: Unconditionally release control of the resources in Example 2 of ENQ. The length 
of the rname for the first resource is 3 characters and the length of the rname for the third 
resource is 8 characters. Allow the length of the second resource to default to its assembled 
length. 

DEQ ( MA JOR4 , MINOR4 , 3 , STEP , MA JOR2 , MINOR2 , , SYSTEM , X 
MA JOR3 , MINOR3 , 8 , SYSTEMS ) 



( 



1 58 Supervisor Services and Macro Instructions 



DEQ (List Form) 



Use the list form of the DEQ macro instruction to construct a DEQ parameter list. The 
number of qname, mame, and scope combinations in the list form of DEQ must be equal to the 
maximum number of qname, mame and scope combinations in any execute form of DEQ that 
refers to that list form. 

The list form of the DEQ macro instruction is written as follows: 



b 

DEQ 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede DEQ. 

One or more blanks must follow DEQ. 



( 



qname addr 
,rname addr 
,rname length 



qname addr: A-type address. 
mame addr: A-type address. 

rname length: symbol or decimal digit. 



f 



) 



,STEP 

,SYSTEM 

.SYSTEMS 



,RET = HAVE 
,RET = NONE 

,RELATED = va/we 

,MF = L 



Default: STEP 



value: any valid macro keyword specification. 



) 



The parameters are explained under the standard form of the DEQ macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the DEQ macro instruction. 
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DEQ (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the DEQ macro. The parameter list can be generated by the list form of either the DEQ or 
the ENQ macro instruction. al.The execute form of the DEQ macro instruction is written as 
follows: 



b 

DEQ 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede DEQ. 

One or more blanks must follow DEQ. 



( 

qname addr 
,rname addr 
,rname length 



Note: ( and ) are the beginning and end of a parameter list. The entire list is 
optional. If nothing in the list is desired, the (, ), and all parameters between ( 
and ) should not be specified. If something in the list is desired, the (, ), and all 
parameters in the list should be specified as indicated at the left. 

qname addr: RX-type address, or register (2) - (12). 

rname addr: RX-type address, or register (2) - (12). 

rname length: symbol, decimal digit or register (2) - (12). 



,STEP 

,SYSTEM 

,SYSTEMS 

) 

,RET = HAVE 

,RET = NONE 

.RELATED = value 
,MF = (E,ctrladdr) 



Default: STEP 



Note: See note opposite ( above. 
Default: RET = NONE 

value: any valid macro keyword specification. 
Ctrl addr: RX-type address, or register (1) - (12). 



The parameters are explained under the standard form of the DEQ macro instruction, with the 
following exception: 

,MF = (E,ctrl addr) 

specifies the execute form of the DEQ macro instruction using a DEQ parameter list. 



1 60 Supervisor Services and Macro Instructions 



) 



J 



DETACH — Detach a Subtask 

The DETACH macro instruction is used to remove from the system a subtask created by an 
ATTACH macro instruction that specified the ECB or ETXR parameter. Each subtask created 
in this manner must be removed from the system before the originating task terminates. 
Failure to remove these subtasks causes abnormal termination of the originating task and all of 
its subtasks. Issuing a DETACH macro instruction that specifies a subtask created without the 
ECB or ETXR parameter also causes abnormal termination of the originating task when the 
specified subtask has already terminated. Issuing a DETACH macro instruction that specifies a 
subtask that has not terminated causes termination of that subtask and all of its subtasks. A 
DETACH macro instruction can be issued only for subtasks created by the active task. 

The DETACH macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 

b One or more blanks must precede DETACH. 
DETACH 

b One or more blanks must follow DETACH. 

tcb addr tcb addr: symbol, RX-type address, or register (1) or (2) - (12). 

,STAE = NO Default: STAE = NO 

,STAE = YES 

,RELATED = value value: any valid macro keyword specification. 

The parameters are explained as follows: 

tcb addr 

specifies the address of a fullword on a fullword boundary containing the address of the 
task control block for the subtask to be removed from the system. 

Note: tcb addr specifies a storage location below 16 Mb. 

,STAE = NO 
,STAE = YES 

specifies whether the exit routine specified in a STAE macro instruction issued by the 
subtask, or STAI/ESTAE/ESTAI exits existing for the subtasks, is or is not to be given 
control if the subtask is detached before it has been terminated. If a retry routine is 
specified by the STAE exit routine, it is not given control. 

,RELATED = va/we 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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The RELATED parameter may be used, for example, as follows: 

ATTCH1 ATTACH EP=MYJOB , ECB=MYECB ,RELATED= (DETCH1 , 
' CREATE SUBTASK ' ) 
ST 1,TCBADDR SAVE TCB ADDRESS 

WAIT 1,MYECB WAIT FOR SUBTASK 

TO COMPLETE 
DETCH1 DETACH TCB ADDR , RELATE D= (ATTCH1, ' DETACH SUBTASK' ) 

Note: The ATTACH macro instruction will fit on one line when coded, so there is no 
need for a continuation indicator. 



When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 

00 

04 



Meaning 

Successful completion. 

An incomplete subtask was detached with STAE = YES specified; DETACH processing successfully 
completed. 



Example 1 



Example 2 



Operation: Cause the subtask to be removed from the address space. The address of the TCB 
is in the fullword labeled SAVEWORD. 

DETACH SAVEWORD 



Operation: In addition to causing the subtask to be removed from the address space, give 
control to the most recent STAE exit established by the subtask if the subtask has not yet been 
terminated. 

DETACH (1),STAE=YES 



( 
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DIV — Data-in-Virtual 



The DIV macro lets you access a data object on permanent storage via paging I/O and process 
this object through normal virtual storage addressing. Data-in-virtual maps the object onto a 
single virtual address range so your program can view it as beginning at a virtual location and 
occupying a consecutive virtual address range. The DIV macro performs the following eight 
services: 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP 

UNACCESS 

UNIDENTIFY 



The standard form of the DIV macro instruction is written as follows: 



) 



b 

DIV 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede DIV. 

One or more blanks must follow DIV. 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP 

UNACCESS 

UNIDENTIFY 

,ID = addr 

, AREA = addr 

,DDNAME = addr 

,MODE = READ 
,MODE = UPDATE 

,OFFSET = addr 
,OFFSET = * 

,RETAIN = YES 
,RETAIN = NO 

,SIZE = addr 
,SIZE = * 

,SPAN = addr 
,SPAN = * 
TYPE = DA 



Valid parameters: 

ID, TYPE, DDNAME 

ID, MODE, SIZE 

ID, AREA, OFFSET, SPAN, RETAIN 

ID, OFFSET, SPAN 

ID, OFFSET, SPAN, SIZE 

ID, AREA, RETAIN 

ID 

ID 



addr: Rx type address or register (2) - (12) 

Default: OFFSET =0 
Default: RETAIN = NO 

See explanation of parameters if omitted 
See explanation of parameters if omitted 
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The IDENTIFY, ACCESS, MAP, SAVE, RESET, UNMAP, UNACCESS and UNIDENTIFY 
parameters, which designate the services of the DIV macro, are mutually exclusive. You can 
select only one. The parameters are explained as follows: 

IDENTIFY 

selects the data-in- virtual object (linear data set) that you want to process. When you 
specify IDENTIFY, you must also specify ID, DDNAME and TYPE. ID specifies the 
address of an eight-byte field, DDNAME specifies the object, and TYPE specifies the 
storage format of the DDNAME. The IDENTIFY service creates a unique eight-byte 
internal name that is returned at the address specified by the ID parameter. This name is 
a token that represents the use of the selected object within your task. When you invoke 
other data-in-virtual services, you use this token as the ID input parameter. 

ACCESS 

requests permission to access a data-in-virtual object. When you specify ACCESS, you 
must also specify ID and MODE and you may optionally specify SIZE. The ID 
parameter, which provides the address of the unique name that was returned by the 
IDENTIFY service, indicates the object you want to access. If SIZE is specified, the 
macro returns the current size of the object in the location that SIZE designates. If 
specified, MODE indicates whether the object will be accessed for reading or updating. 

MAP 

specifies a request to establish addressability to the object in a specified range of virtual 
storage, called the virtual window. When you specify MAP, you must also specify ID and 
AREA, and you may optionally specify OFFSET, SPAN, and RETAIN. The ID 
parameter, which provides the address of the unique name that was returned by the 
IDENTIFY service, selects the object that you want to map. AREA indicates the starting 
address of the virtual window. OFFSET and SPAN specify the range of blocks on the 
object that is to be mapped to the window. RETAIN indicates whether or not data 
previously existing in the virtual window is kept, or replaced by data from the object data. 

RESET 

releases changes made in the window since the last SAVE operation. When you specify 
RESET, you must also specify ID, and you may optionally specify OFFSET and SPAN. 
ID, which provides the address of the unique name that was returned by the IDENTIFY 
service, indicates the virtual window that you want to reset. OFFSET and SPAN specify 
the range of blocks on the object that corresponds to the virtual window. Data in pages of 
mapped virtual windows that correspond to the RESET range will be replaced. If the 
window corresponds to blocks on the object, the data is replaced by the current contents 
of the object. If the window corresponds to blocks offset beyond the end of the object, the 
data is not relevant (as if the pages had just been obtained by a GETMAIN). No change 
to the object itself will be made by a RESET. 

SAVE 

specifies that data from the window is to be saved. Saving is accomplished by writing 
changed pages from the window to the corresponding blocks of the object. When you 
specify SAVE, you must also specify ID, and you may optionally specify OFFSET, SPAN 
and SIZE. ID, which specifies the unique name that was returned by the IDENTIFY 
service, selects the object into which the blocks are written. OFFSET and SPAN specify 
the data blocks, relative to the beginning of the object, that are to be saved. Changed 
pages from the window are then written into those blocks. 



i 
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UNMAP 

specifies a request to terminate a virtual window by removing the correspondence between 
virtual pages in the window and blocks on the object. After the UNMAP is complete, the 
contents of the pages depend on the value you specify for RETAIN; the virtual pages in 
the former window either retain a copy of the data that was on the corresponding blocks 
of the object, or appear as if they had just been obtained by a GETMAIN. 

When you specify UNMAP, you must also specify ID and AREA, and you may specify 
RETAIN. ID provides the address of the unique name that was returned by the 
IDENTIFY service, the same name that was input to the MAP service that created the 
window. AREA specifies the starting address of the virtual window. RETAIN specifies 
whether data from the object is to be retained or discarded. If you specify 
RETAIN = YES, the data from the object is retained in virtual storage. If you specify 
RETAIN = NO, the data is discarded from virtual storage, leaving the appearance of data 
that has been just obtained by a GETMAIN. RETAIN = NO is the default. UNMAP has 
no effect on the object itself and does not save data from the virtual window. If you want 
to save the data in the window, then invoke the SAVE before you invoke UNMAP. 

UNACCESS 

specifies that you are relinquishing your permission to read from or write to a 
data-in-virtual object. When you specify UNACCESS, you must also specify ID, which 
provides the address of the unique name that was returned by the IDENTIFY service. 
When UNACCESS is invoked, any outstanding windows for the specified ID are 
automatically unmapped with an implied RETAIN = NO. 

UNIDENTIFY 

specifies that the use of a data-in-virtual object under a previously assigned ID is ended. 
When you specify UNIDENTIFY, you must also specify ID, which provides the address 
of the unique name that was returned by the IDENTIFY service. If the object is still 
accessed or mapped under the specified ID, the system will automatically unaccess and 
unmap it with an implied RETAIN = NO. 

,ID = addr 

specifies the address of a field in storage where the IDENTIFY service stores a unique 
eight-byte name that it associates with the object. This name, which is like a token, is the 
output value of the IDENTIFY service; it is a required input value for all the other 
services. 

,AREA = address 

specifies the address of a four-byte field in storage containing a pointer to the start of the 
virtual window. The AREA parameter must be specified when you invoke the MAP and 
the UNMAP services. The starting address for an UNMAP request must be identical to 
the starting address of its corresponding MAP request. The virtual storage area that is 
occupied by a window must meet the following requirements: 

• The window must begin on a 4096-byte (page) boundary and must be a multiple of 
4096 bytes long. 



J 



• Virtual storage within the window must have been obtained by the GETMAIN macro 
from a single, pageable, private area subpool owned by the task that issued the 
IDENTIFY. 

• The window cannot contain VIO storage. 

• Pages within the window cannot be page fixed. 
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DDNAME = addr 

specifies the address of a field containing the ddname for the object. The first byte of the 
field must be the number of characters in the ddname. The bytes following the first byte 
must contain the EBCDIC characters of the ddname itself. The ddname must conform to 
the standard syntax for ddnames. (One through eight alphameric or national characters, 
the first of which must be alphabetic or national.) DDNAME is required when you 
invoke IDENTIFY but it is not allowed when you invoke other services of the DIV 
macro. 

,MODE = READ 
,MODE = UPDATE 

specifies whether the object is being accessed for the purpose of reading or updating. If 
you are using the SAVE service to update an object, specify MODE = UPDATE. 
Otherwise, specify MODE = READ to signify read-only access to the object. MODE must 
be specified whenever you specify ACCESS. 

,OFFSET = addr 
,OFFSET = * 

specifies the beginning of a continuous string of blocks in a data-in-virtual object. 
OFFSET is used with SPAN to define a continuous string of blocks in an object. 
OFFSET designates the location of the first block in the string, and SPAN designates 
how many blocks are in the string. An OFFSET value of zero designates the first block 
(the beginning) of an object. An OFFSET beyond the current end of the object is 
permitted as long as it remains within the maximum number of blocks allowed for the 
object and also within the absolute limit of (2**20)- 1. if you omit offset or specify 
offset = *, a default OFFSET of zero is used. The OFFSET parameter can be specified 
with the MAP, RESET, and SAVE services. 

,RETAIN = YES 
,RETAIN = NO 

specifies the retain mode of the window, which controls the actions of the MAP, 
UNMAP, and SAVE services. The retain mode determines what data appears in the 
window when the MAP service is invoked, and what data is left in virtual storage when 
UNMAP is invoked. It also affects how blocks are saved when you invoke the SAVE 
service, and how blocks are reset when you invoke RESET. The RETAIN parameter may 
be specified when you specify the MAP and the UNMAP parameters of the DIV macro. 
If the RETAIN parameter is not specified, the retain mode defaults to NO. 

,SIZE =addr 
,SIZE = * 

specifies the address of a four-byte field where the system stores the size of the object. The 
size is stored in this field as a return value whenever you specify SAVE or ACCESS and 
also specify SIZE. When control is returned after the execution of a SAVE, the value that 
is returned is the minimum number of blocks that must be mapped to ensure that the 
entire object is mapped. If you omit SIZE or specify SIZE = *, then the size is not 
returned. 

The size parameter may only be specified when you specify MAP, RESET, or SAVE. 
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,SPAN =addr 
,SPAN = * 

specifies the address of a four-byte field containing the number of blocks that are to be 
processed by the MAP, RESET, or SAVE services. These services operate only on a string 
of contiguous blocks. SPAN indicates how many blocks are in the string. It is used with 
OFFSET, which indicates the first block of the string. 

For the RESET and SAVE services, the block string can include discontiguous mappings 
of an object. This lets you reset or save several maps in a single DIV macro invocation. 

For the MAP service, the block string can extend beyond the end of the object, but it 
cannot extend beyond the maximum size allowed for the object. You can create a window 
that exceeds the size of the object. The maximum span allowed is (2**20)-l bytes. 

If you omit SPAN or specify SPAN = *, the SPAN default value is used. The default is 
also be used if the four-byte field contains zero. For the SAVE and RESET services, the 
default value is the number of blocks in the object from the specified or defaulted block 
to the end of the last mapped range. For the MAP service, the default is the current size 
of the object in blocks, minus the value specified by OFFSET. If the offset value is 
beyond the end of the object, the span defaults to one when you omit SPAN. 

SPAN may be specified only when you specify MAP, RESET or SAVE. 



) 



,TYPE = DA 

specifies that your program is using a data definition statement to identify the object. You 
must specify TYPE = DA whenever you specify IDENTIFY. 



) 
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DIV (List Form) 



The list form of the DIV macro instruction is written as follows: 



b 
DIV 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede DIV. 

One or more blanks must follow DIV. 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP. 

UNACCESS 

UNIDENTIFY 

,AREA = addr 

,DDNAME = addr 

,ID = addr 

,MODE = READ 
,MODE = UPDATE 

.TYPE = DA 

,OFFSET = addr 
,OFFSET = * 

.RETAIN = YES 
.RETAIN = NO 

,SIZE = addr 
,SIZE = * 



Valid parameters: 

ID, TYPE, DDNAME 

ID, MODE, SIZE 

ID, AREA, OFFSET, SPAN, RETAIN 

ID, OFFSET, SPAN 

ID, OFFSET, SPAN, SIZE 

ID, AREA, RETAIN 

ID 

ID 

Initialized to zero if omitted 
addr: A-type address 

Initialized to zero if omitted 

Initialized to zero if omitted 

Initialized to zero if omitted 

Initialized to zero if omitted 
Default: OFFSET = 0. 

Default: RETAIN.= NO 

See explanation of parameters if omitted 



,SPAN = addrSee explanation of parameters if omitted 

,SPAN = * 



,MF = L 



,MF = L 

specifies the list form of the DIV macro. The list form generates the DIV parameter list 
in line without any executable code or register usage. 
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DIV (Execute Form) 



The execute form of the DIV macro instruction is written as follows: 



b 

DIV 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede DIV. 

One or more blanks must follow DIV. 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP 

UNACCESS 

UNIDENTIFY 

,AREA = addr 

,DDNAME = a<tar 

,ID = addr 

,MODE = READ 
,MODE = UPDATE 

,TYPE = DA 

,OFFSET = addr 
,OFFSET = * 

.RETAIN = YES 
.RETAIN = NO 

,S\.ZE = addr 
,SIZE = * 

,SPAN = addr 

,SPAN = * 

,MF = (E,a#) 



Valid parameters: 

ID, TYPE, DDNAME 

ID, MODE, SIZE 

ID, AREA, OFFSET, SPAN, RETAIN 

ID, OFFSET, SPAN 

ID, OFFSET, SPAN, SIZE 

ID, AREA, RETAIN 

ID 

ID 

No change in executable parameter list if omitted 
addr: Rx type address or register (2) - (12) 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 
Default: OFFSET =0 

Default: RETAIN = NO 

See explanation of parameters if omitted 
See explanation of parameters if omitted 



) 



,MF = (E,addr) 

specifies the Execute form. In the Execute form, DIV will be called using the parameter 
list specified by "addr." "addr" indicates the address of the parameter list and may be (a) 
any address that is valid in an RX-type assembler language instruction or (b) one of the 
general registers 2 through 12 specified within parentheses. The register may be expressed 
either symbolically or as a decimal number. The specified parameter list will be updated 
for any parameters that are specified. Other parameter fields will be unaffected. 
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DIV (Modify Form) 



The modify form of the DIV macro instruction is written as follows: 



b 

DIV 

b 



One or more blanks must precede DIV. 



One or more blanks must follow DIV. 



IDENTIFY 

ACCESS 

MAP 

RESET 

SAVE 

UNMAP 

UNACCESS 

UNIDENTIFY 

,AREA = addr 

,DDNAME = arf* 

,ID = addr 

,MODE = READ 
,MODE = UPDATE 

/TYPE = DA 

,OFFSET = <Ktar 
,OFFSET = * 

,RETAIN = YES 
,RETAIN = NO 

,SIZE = addr 
,SIZE = * 

,SPAN = addr 
,SPAN = * 

,MF = (M,addr) 



Valid parameters: 

ID, TYPE, DDNAME 

ID, MODE, SIZE 

ID, AREA, OFFSET, SPAN, RETAIN 

ID, OFFSET, SPAN 

ID, OFFSET, SPAN, SIZE 

ID, AREA, RETAIN 

ID 

ID 

No change in executable parameter list if omitted 
addr: Rx type address or register (2) - (12) 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 

No change in executable parameter list if omitted 
Default: OFFSET = 

Default: RETAIN = NO 

See explanation of parameters if omitted 

See explanation of parameters if omitted 

See explanation of parameters if omitted. 



,MF-(M,<KWr) 

specifies the MODIFY form. The modify form of the macro is used to modify an already 
defined DIV parameter list. It is exactly the same as the EXECUTE form except that 
DIV is not called. Registers 1 and 1 5 are destroyed. 



< 
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DOM — Delete Operator Message 



The DOM macro instruction is used to delete an operator message or group of messages from 
the display screen of the operator's console. It can also prevent messages from ever appearing 
on any operator's console. When a program no longer requires that a message be displayed, it 
can issue the DOM macro instruction to delete the message. 

Depending on the timing of the DOM relative to the WTO(R), the message may or may not be 
displayed. If the message is being displayed, it is removed when space is required for other 
messages. 

When a WTO or WTOR macro instruction is issued, the system assigns an identification 
number to the message and returns this number (24 bits right-justified) to the issuing program 
in general register 1 . When the display of this message is no longer needed, you can issue the 
DOM macro instruction using the identification number that was returned in general register 1 . 

The DOM macro instruction is written as follows: 



name 
b 

DOM 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede DOM. 

One or more blanks must follow DOM. 



MSG = addr 
MSGLIST = list addr 
TOKEN = addr 

,COUNT = arfrfr 

,REPLY = YES 



addr: register (1) - (12), or an address. 

list addr: symbol, RX-type address, or register (1) - (12). 

addr: register (1) - (12), or an address. 

addr: register (2) - (12), or an address. 



The parameters are explained as follows: 

MSG = 
MSGLIST = 

specifies the message numbers of messages to be deleted. 

For MSG, the address or register contains the 24-bit, right-justified 
identification number of the message to be deleted. Use this parameter to delete a 
single message. If you use register 1, the macro expansion is shortened by two bytes. 

For MSGLIST, the address is of a list of one or more fullwords, each word containing a 
24-bit, right-justified identification number of a message to be deleted. A maximum of 60 
identification numbers may be in the message list. If more than 60 identification numbers 
are in the list, only the first 60 are processed. Begin the list on a fullword boundary. 
When you are not using the COUNT parameter, indicate the end of the list by setting the 
high-order bit of the last fullword entry to 1. If you use register 1, the macro expansion is 
shortened by four bytes. If any register from 2 through 12 is used, the macro expansion is 
shortened by two bytes. 
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,COUNT = 

The count field or register contains the one-byte count of 4-byte DOM ids associated with 

this request. The count value must be from 1 to 60. If this keyword is used, the issuer j 

must not set the high order bit on in the last entry of the DOM parameter list. If this 

keyword is not specified, the DOM ids are treated as 3-byte ids. If an address is used 

instead of a register, the address points to a 1-byte field which contains the count. The 

COUNT keyword is invalid with the TOKEN keyword. 

,REPLY = YES 

specifies that the need for a reply to a WTOR message has been eliminated. 
REPLY = YES is invalid with TOKEN and COUNT. When you specify REPLY = YES, 
you must specify either MSG or MSGLIST to identify the message or group of messages 
that is to be deleted. 

TOKEN - 

The field or register contains the 4-byte TOKEN of the messages that are to be deleted. 
The messages that are deleted by TOKEN are the messages that were issued with this 
TOKEN via WTO. Unauthorized users may delete only those messages which were 
originally issued under the same jobstep TCB, ASID and system id. No DOM ids can be 
specified with this keyword. This keyword is mutually exclusive with the MSG, 
MSGLIST, and COUNT keywords. 

Note: For any DOM keywords that allow a register specification, the value must be 
right-justified in the register and the remaining bytes within the register must be zero. 

Example 1 

Operation: Delete an operator message whose message id is in register 1 . I 

DOM MSG=(1) 

Example 2 

Operation: Delete a list of operator messages, some of which may be WTORs. 

DOM MSGLIST=ID2,REPLY=YES 

Example 3 

Operation: Delete a number of operator messages. The COUNT parameter indicates how 
many messages are to be deleted. 

DOM MSGLIST=ID3,COUNT=COUNT4 
Example 4 

Operation: Delete all messages issued with a particular token. 

DOM TOKEN=TOKENl 



< 
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ENQ — Request Control of a Serially Reusable Resource 

ENQ requests the control program to assign control of one or more serially reusable resources 
to the active task. If any of the resources are not available, the active task might be placed in a 
wait condition until all of the requested resources are available. Once control of a resource has 
been assigned to a task, it remains with that task until a DEQ macro instruction is issued or the 
task terminates. Register 1 5 is set to if the request is satisfied. 

You can also use ENQ to determine the status of the resource; whether it is immediately 
available or in use, and whether control has been previously requested for the active task in 
another ENQ macro instruction. 

You can request either shared or exclusive use of a resource. The resource is represented in the 
ENQ by a pair of names, the qname and the rname, and a scope value. In order for ENQ/DEQ 
to coordinate the use of the resources: 

• Everyone must use ENQ/DEQ. 

• Everyone must use the same names and scope values for the same resources. 

• Everyone must use consistent ENQ/DEQ protocol. . 

Issuing two ENQ macro instructions for one task for the same resource without an intervening 
DEQ macro instruction results in abnormal termination of the task, unless the second ENQ 
designates RET = TEST, USE, CHNG, or HAVE. If a task terminates while it still has control 
of any resources, all requests that this task made are automatically dequeued. 

Global resource serialization counts and limits the number of concurrent resource requests from 
an address space. If an unconditional ENQ (an ENQ that uses the RET = NONE option) 
causes the count of concurrent resource requests to exceed the limit, the caller is abended with a 
system code of X'538'. See "Limiting Concurrent Requests for Resources" in Part I. 

Note: When global resource serialization is active, the SYSTEM inclusion resource name list 
and the SYSTEMS exclusion resource name list are searched for every resource specified with a 
scope of SYSTEM or SYSTEMS. A resource whose name appears in one of these resource 
name lists might have its scope changed from the scope that appears on the macro instruction. 
See Planning: Global Resource Serialization for more information. 



) 
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The standard form of the ENQ macro instruction is written as follows: 



b 

ENQ 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 

qname addr 
rname addr 

E 
S 

rname length 



,STEP 

.SYSTEM 

,SYSTEMS 

) 



,RET = CHNG 
,RET = HAVE 
,RET = TEST 
,RET = USE 
,RET = NONE 

.RELATED rvalue 



qname addr: A-type address, or register (2) - (12). 
rname addr: A-type address, Or register (2) - (12). 
Default: E 

rname length: symbol, decimal digit, or register (2) - (12). 
Default: assembled length of rname 

Default: STEP 



Default: RET = NONE 



value: any valid macro keyword specification. 



The parameters are explained as follows: 



specifies the beginning of the resource(s) description. 

qname addr 

specifies the address in virtual storage of an 8-character name. The name can contain any 
valid hexadecimal character. Every program issuing a request for a serially reusable 
resource must use the same qname, rname, and scope to represent the resource. (See the 
section "Naming the Resource" for restrictions on naming qname.) 

,mame addr 

specifies the address in virtual storage of the name used in conjunction with qname to 
represent a single resource. The name must be from 1 to 255 bytes long and can contain 
any valid hexadecimal characters. The rname length must be specified if either the name 
specified in the rname field, or the length attribute on the rname is defined by an EQU 
assembler instruction. Additionally, the rname length must be coded if the rname addr 
field is coded as a register. 



,E 

,S 



specifies whether the request is for exclusive (E) or shared (S) control of the resource. If 
the resource is modified while under control of the task, the request must be for exclusive 
control; if the resource is not modified, the request should be for shared control. 



( 
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,rname length 

specifies the length of the rname described above. If this parameter is omitted, the 
assembled length of the rname is used. You can specify a value between 1 and 255 to 
override the assembled length, or you may specify a value of 0. If is specified, the 
length of the rname must be contained in the first byte at the rname addr specified above. 
This rname length parameter may be specified as an explicit constant (decimal digit), a 
label from an EQU assembler instruction (symbol), or a register (2)-(12). The rname 
length must be specified if either the name specified in the rname field, or the length 
attribute of the rname is defined by an EQU assembler instruction. Additionally, the 
rname length must be coded if the rname addr field is coded as a register. 



,STEP 

,SYSTEM 

,SYSTEMS 

specifies the scope of the resource used only within an address space (STEP), used by 
programs of more than one address space (SYSTEM), or shared between systems 
(SYSTEMS). If STEP is specified, a request for the same qname and rname from a 
program in another address space denotes a different resource. If SYSTEM or 
SYSTEMS is specified, requests for the same qname, rname, and scope from programs of 
any address space denote the same resource. 

STEP, SYSTEM, and SYSTEMS are mutually exclusive and do not refer to the same 
resource. If two macro instructions specify the same qname and rname, but one specifies 
STEP and the other specifies SYSTEM or SYSTEMS, they are treated as requests for 
different resources. 

Note: The SYSTEM option is not the same as the SYSTEMS option. When you specify 
SYSTEMS, you are spreading the scope of the resource across two or more processors. 
SYSTEM confines the scope to a single processor, but it includes two or more address 
spaces in the scope of the resource. 



specifies the end of the resource(s) description. 

Note: The parameters qname addr, rname addr, type of control, rname length, and the 
scope can be repeated within a single set of parentheses to indicate multiple resources. 
These parameters can be repeated until there is a maximum of 255 characters including 
the parentheses. 

,RET = CHNG 
,RET = HAVE 
,RET = TEST 
,RET = USE 
,RET = NONE 

specifies the type of request for all of the resources named above. 

CHNG - the status of the resource specified is to be changed from shared to exclusive 
control. 

HAVE - control of the resources is requested conditionally; that is, control is requested 
only if a request has not been made previously for the same task. 
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TEST - the availability of the resources is to be tested, but control of the resources is 
not requested. 

USE - control of the resources is to be assigned to the active task only if the resources 
are immediately available. If any of the resources are not available, the active 
task is not placed in a wait condition. 

NONE - control of all the resources is unconditionally requested. 

,RELATED = va/«e 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETAGH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

ENQUEUE ENQ ( MAJOR, MINOR, S, 8 , STEP) , X 

RELATED= ( DEQUEUE , ' OBTAIN RESOURCE ' ) 



DEQUEUE DEQ ( MAJOR, MINOR, 8 , STEP) , X 

RELATED= ( ENQUEUE , ' RELEASE RESOURCE ' ) 

Return codes are provided by the control program only if you specify RET = TEST, 
RET = USE, RET = CHNG, or RET = HAVE; otherwise, return of the task to the active 
condition indicates that control of the resource has been assigned (or previously assigned) to the 
task. If all return codes for the resources named in the ENQ macro instruction are 0, register 
15 contains 0. If any of the return codes are not 0, register 15 contains the address of a storage 
area containing the return codes, as shown in Figure 52. The return codes are placed in the 
parameter list resulting from the macro expansion in the same sequence as the resource names 
in the ENQ macro instruction. The return codes are shown in Figure 53. 
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Address 
Returned in 
Register 15 



Return 
Codes 



12 



24 



36 



) 



12 



RC 1 



RC 2 



RC 3 






< i 



Return codes are 
1 2 bytes apart, 
starting 3 bytes 
from the address 
in register 15. 



RC N 



Figure 52. Return Code Area Used by ENQ 



Hexadecimal 
Code 



14 



Meaning 

For RET = TEST, the resource was immediately available. 

For RET = USE or RET = HAVE, control of the resource has been assigned to the active task. 

For RET = CHNG, the status of the resource has been changed to exclusive. 

For RET = TEST or RET = USE, the resource is not immediately available. 
For RET = CHNG, the status cannot be changed to exclusive. 

For RET = TEST, RET = USE, or RET = HAVE, this task has made a previous request for control of 

the same resource and this task has control of the resource. 

If bit 3 of the first byte of this entry in the ENQ parameter list is on, this task has shared control of the 

resource; if bit 3 is off, this task has exclusive control. 

For RET = CHNG, the resource was not queued or was not previously requested by the requesting task. 

This task has made a previous request for control of the same resource, and this task does not have 
control of resource. 



18 



For RET = HAVE or RET = USE, the limit for the number of concurrent resource requests has been 
reached. The task does not have control of the resource unless some previous ENQ request caused the 
task to obtain control of the resource. 



Figure 53. ENQ Return Codes 



) 
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Example 1 

Operation: Conditionally request shared control of a serially reusable resource that is known 
only within the address space (STEP). The resource is only to be obtained if immediately 
available. The resource will be used for read-only purposes. The length of rname is allowed to 
default. 

ENQ (MAJ0R1,MIN0R1,S, ,STEP) ,RET=USE 

Example 2 

Operation: Unconditionally request exclusive control of 3 resources. The scope of each 
resource differs (STEP, SYSTEM, and SYSTEMS respectively). The rname length of the first 
resource is 3 characters and the rname length of the third resource is 8 characters. Allow the 
rname length of the second resource to default to its assembled length. 

ENQ (MAJOR4,MINOR4,E,3, ,MAJOR2 ,MINOR2 , , , SYSTEM, X 
MA JOR3 , MIN0R3 , E , 8 , SYSTEMS ) 



( 



178 Supervisor Services and Macro Instructions 



ENQ (List Form) 



Use the list form of ENQ to construct a control program parameter list. Any number of 
resources can be specified in the ENQ macro instruction; therefore, the number of qname, 
rname, and scope combinations in the list form the ENQ macro instruction must be equal to the 
maximum number of qname, rname, and scope combinations in any execute form of the macro 
instruction that refers to that list form. 

The list form of the ENQ macro instruction is written as follows: 



b 

ENQ 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 



) 



qname addr 
rname addr 

!e 

,S 

,rname length 



,STEP 

.SYSTEM 

.SYSTEMS 



qname addr: A-type address. 
rname addr: A-type address. 

Default: E 



rname length: symbol or decimal digit. 
Default: assembled length of rname 

Default: STEP 



,RET = CHNG 
,RET = HAVE 
,RET = TEST 
,RET = USE 
,RET=NONE 

.RELATED = value 
,MF=L 



Default: RET = NONE 



value: any valid macro keyword specification. 



) 



The parameters are explained under the standard form of the ENQ macro instruction, with the 
following exception: 

,MF=L 

specifies the list form of the ENQ macro instruction. 



ENQ (List Form) 179 



ENQ (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the ENQ macro instruction. The parameter list can be generated by the list form of ENQ. 

The execute form of the ENQ macro instruction is written as follows: 



b 
ENQ 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ENQ. 

One or more blanks must follow ENQ. 



( 

qname addr 
rname addr 

,S 

,rname length 



Note: ( and ) are the beginning and end of a parameter list. The entire list is 
optional. If nothing in the list is desired, then (, ), and all parameters between 
( and ) should not be specified. If something in the list is desired, then (, ), and 
all parameters in the list should be specified as indicated at the left. 

qname addr: RX-type address, or register (2) - (12). 

rname addr: RX-type address, or register (2) - (12). 

Default: E 



rname length: symbol, decimal digit, or register (2) - (12). 



,STEP 

.SYSTEM 

.SYSTEMS 

) 

,RET = CHNG 
,RET = HAVE 
,RET = TEST 
,RET = USE 
,RET = NONE 

.RELATED = value 
,MF = (E,ctrladdr) 



Default: STEP 

Note: See note opposite ( above. 
Default: RET = NONE 



value: any valid macro keyword specification. 
Ctrl addr: RX-type address, or register (1) - (12). 



i 



The parameters are explained under the standard form of the ENQ macro instruction, with the 
following exception: 

,ME = (E,ctrladdr) 

specifies the execute form of the ENQ macro instruction using a remote control program 
parameter list. 



( 
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) 



) 



ESPIE - Extended SPIE 

The ESPIE macro instruction extends the function of the SPIE (specify program interruption 
exits) macro instruction to callers in 31 -bit addressing mode. Callers in either 24-bit or 31 -bit 
addressing mode can issue the ESPIE macro instruction. Only callers in 24-bit addressing mode 
can issue the SPIE macro instruction. For additional information concerning the relationship 
between the SPIE and the ESPIE macro instructions, see the section "Interruption Services" in 
Part I. 

The ESPIE macro instruction performs the following functions using the options specified: 

• Establishes an ESPIE environment (that is, identifies the interruption types that are to 
cause entry to the ESPIE exit routine) by executing the SET option of the ESPIE macro 
instruction. 

• Deletes an ESPIE environment (that is, cancels the current SPIE/ESPIE environment) by 
executing the RESET option of the ESPIE macro instruction. 

• Determines the current SPIE/ESPIE environment by executing the TEST option of the 
ESPIE macro instruction. 

SET Option 

The SET option of the ESPIE macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede ESPIE. 
ESPIE 

b One or more blanks must follow ESPIE. 

SET 

,exit addr exit addr: A-type address, or register (2) - (12). 

^interruptions) interruptions: decimal digits 1-15 and expressed as: 

single values: (2, 3, 4, 7, 8, 9, 10) 
ranges of values: ((2, 4), (7, 10)) 
combinations: (2, 3, 4, (7, 10)) 

,PARAM = list addr list addr: A-type address or register (2) - (12). 

The parameters are explained as follows: 

SET 

indicates that an ESPIE environment is to be established. 

,exit addr 

specifies the address of the exit routine to be given control when program interruptions of 
the type specified by interruptions occur. The exit routine receives control in the same 
addressing mode as the issuer of the ESPIE macro instruction. 



) 
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,C interruptions) 

indicates the interruption types that are being trapped. The interruption types are: 

Number Interruption Type 



1 

2 
3 


Operation 

Privileged operation 
Execute 


4 


Protection 


5 
6 

7 


Addressing 

Specification 

Data 


8 
9 
10 
11 


Fixed-point overflow (maskable) 
Fixed-point divide 
Decimal overflow (maskable) 
Decimal divide 


12 
13 
14 
15 


Exponent overflow 
Exponent underflow (maskable) 
Significance (maskable) 
Floating-point divide 



These interruption types can be designated as one or more single numbers, as one or more 
pairs of numbers (designating ranges of values), or as any combination of the two forms. 
For example, (4,8) indicates interruption types 4 and 8; ((4,8)) indicates interruption types 
4 through 8. 

If a program interruption type is maskable, the corresponding program mask bit in the 

PSW is set to 1. If a maskable interruption is not specified, the corresponding bit in the 

PSW is set to 0. Interruption types not specified above (except for type 17, which is 

described in SPL: System Macros and Facilities) are handled by the control program. 

The control program forces an abend with the program check as the completion code. If 

an ESTAE-type recovery routine is also active, the SDWA indicates a system-forced 1 

abnormal termination. The registers at the time of the error are those of the control 

program. 

Note: For both ESPIE and SPIE - If you are using vector instructions and an exception 
of 8, 12, 13, 14, or 15 occurs, your recovery routine can check the exception extension 
code (the first byte of the two-byte interruption code in the EPIE or PIE) to determine 
whether the exception was a vector or scalar type of exception. 

,PARAM = list addr 

specifies the fullword-address of a parameter list that is to be passed by the caller to the 
exit routine. 

On return from the SET option of the ESPIE macro instruction, the registers contain the 
following information: 

Register Content 

Unpredictable 

1 Token representing the previously active SPIE/ESPIE environment 
2-13 Unchanged 

14 Unpredictable 

15 Return code of 
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Example 1 



Operation: Give control to an exit routine for interruption types 1 and 4. EXIT is the location 
of the exit routine to be given control and PARMLIST is the location of the user parameter list 
to be used by the exit routine. 

ESPIE SET, EXIT, (1,4) , PARAM=PARMLIST 



RESET Option 



> 



> 



The RESET option of the ESPIE macro cancels the current SPIE/ESPIE environment and 
re-establishes the previously active SPIE/ESPIE environment identified by the token specified. 

The RESET option of the ESPIE macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede ESPIE. 
ESPIE 

b One or more blanks must follow ESPIE. 

RESET 

,token token: RX-type address, or register (1), (2) - (12). 



The parameters are explained as follows: 

RESET 

indicates that the current ESPIE environment is to be deleted and the previously active 
SPIE/ESPIE environment specified by token is to be re-established. 

,token 

specifies a fullword that contains a token representing the previously active SPIE/ESPIE 
environment. This is the same token that ESPIE processing returned to the caller when 
the ESPIE environment was established using the SET option of the ESPIE macro 
instruction. 

If the token is zero, all SPIEs and ESPIEs are deleted. 

On return from ESPIE RESET, the contents of the registers are as follows: 

Register Contents 

Unpredictable 

1 Token identifying the new active SPIE/ESPIE environment 
2-13 Unchanged 

14 Unpredictable 

15 Return code of 
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Example 1 



Operation: Cancel the current SPIE/ESPIE environment and restore the SPIE/ESPIE 
environment represented by the contents of TOKEN. 



ESPIE RESET, TOKEN 



TEST Option 



The TEST option of the ESPIE macro instruction determines the active SPIE/ESPIE 
environment and returns the information in a four-byte parameter list. 

The TEST option of the ESPIE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede ESPIE. 
ESPIE 

b One or more blanks must follow ESPIE. 

TEST 

,parm addr parm addr: RX-type address, or register (1), (2) - (12). 



The parameters are explained as follows: 

TEST 

indicates a request for information concerning the active or current SPIE/ESPIE 
environment. ESPIE processing returns this information to the caller in a four-word 
parameter list located at parm addr. 

iparm addr 

specifies the address of a four-word parameter list aligned on a fullword boundary. The 
parameter list has the following form: 

Word Content 

Address of the user-exit routine (31 -bit address with the h^gh-order bit set to 0) 

1 Address of the user-defined parameter list 

2 Mask of program interruption types (Note: Bit 1 corresponds to interrupt code 1, bit 2 to interrupt code 
2, and so on.) 

3 Zero 



< 
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On return from ESPIE TEST, the registers contain the following information: 
Register Contents 






Unpredictable 


1-13 


Unchanged 


14 


Unpredictable 


15 


Return code as follows: 




Code Meaning 




An ESPIE exit i 



Example 1 



An ESPIE exit is active and the four-word parameter list contains the information described under 
the parm addr parameter of the ESPIE macro instruction. 

A SPIE exit is active and word 1 of the parameter list contains the address of the current PICA. 
Words 0, 2, and 3 of the parameter list are unpredictable. 

A SPIE or ESPIE exit is not active. All the words of the parameter list are unpredictable. 



Operation: Identify the active SPIE/ESPIE environment. Return the information about the 
exit routine in the four-word parameter list, PARMLIST. Also return, in register 15, an 
indicator of whether a SPIE, ESPIE, or neither is active. 

ESPIE TEST, PARMLIST 



> 



) 
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ESPDE (List Form) 



The list form of the ESPIE macro instruction builds a non-executable problem program 
parameter list that can be referred to or modified by the execute form of the ESPIE macro 
instruction. 

The list form of the ESPIE macro instruction is written as follows: 



name 
b 

ESPIE 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ESPIE. 

One or more blanks must follow ESPIE. 



SET 



,exit addr 



^interruptions) 



exit addr: A-type address. 

Note: This parameter must be specified on either the list or the execute form of 

the macro instruction. 

interruptions: decimal digit 1-15 and expressed as: 



,PARAM = list addr 
,MF = L 



single values: (2, 3, A, 7, 8, 9, 10) 
range of values: ((2, 4), (7, 10)) 
combinations: (2, 3, 4, (7, 10)) 

list addr: A-type address. 



Example 1 



The parameters are explained under the standard form of the ESPIE macro instruction with the 
following exception: 

,MF = L 

specifies the list form of the ESPIE macro instruction. 



Operation: Build a non-executable problem program parameter list that will cause control to 
be transferred to the exit routine, EXIT for the interruption types specified in the execute form 
of the macro instruction. Provide the address of the user parameter list, PARMLIST. 

LISTl ESPIE SET , EXIT, ,PARAM=PARMLIST,MF=L 



< 
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ESPIE (Execute Form) 



The execute form of the ESPIE macro instruction can refer to and modify the parameter list 
constructed by the list form of the ESPIE macro instruction. 

The execute form of the ESPIE macro instruction is written as follows: 



name 
b 

ESPIE 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ESPIE. 

One or more blanks must follow ESPIE. 



SET 



,exit addr 



^interruptions) 



exit addr: RX-type address or register (2) - (12). 

Note: This parameter must be specified on either the list or the execute form of 

the macro instruction. 

interruptions: decimal digit 1-15 and expressed as: 



,PARAM = list addr 
,MF = (E,ctrladdr) 



single values: (2, 3, 4, 7, 8, 9, 10) 
range of values: ((2, 4), (7, 10)) 
combinations: (2, 3, 4, (7, 10)) 

list addr: RX-type address or register (2) - (12). 
ctrl addr: RX-type address, or register (1), (2) - (12). 



) 



The parameters are explained under the standard form of the ESPIE macro instruction with the 
following exception: 

,MF = (E,ctrladdr) 

specifies the execute form of the ESPIE macro instruction using a remote control program 
parameter list. 



Example 1 



) 



Operation: Give control to a user exit routine for interruption types 1, 4, 6, 7, and 8. The exit 
routine address and the address of a user parameter list for the exit routine are provided in a 
remote control program parameter list at LIST1. 

ESPIE SET, , (1,4, (6,8) ) ,MF= (E,LIST1) 
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ESTAE — Extended Specify Task Abnormal Exit 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. ESTAE exits and retry routines execute in the same address mode as 
the program that issues the ESTAE macro instruction. 

The ESTAE macro instruction provides recovery capability facilities. Issuance of the ESTAE 
macro instruction or ATTACH with the STAI (specify task abnormal interrupts) or ESTAI 
(extended STAI) option allows the user to intercept a scheduled ABEND. Control is given to a 
user specified exit routine in which the user may perform pre-termination processing, diagnose 
the cause of ABEND, and specify a retry address if he wishes to avoid the termination. These 
exits operate in both problem program and supervisor modes. 

The standard form of the ESTAE macro instruction is written as follows: 



name 
b 

ESTAE 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ESTAE. 

One or more blanks must follow ESTAE. 



exit addr 


,CT 
,OV 



,P ARAM = list addr 

,XCTL = NO 
,XCTL = YES 

,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 

,ASYNCH = YES 
,ASYNCH = NO 

,TERM = NO 
,TERM = YES 

,RELATED = va/we 



exit addr: A-type address, or register (2) - (12). 

Default: CT 

list addr: A-type address, or register (2) - (12). 

Default: XCTL = NO 

Default: PURGE = NONE 

Default: ASYNCH = YES 
Default: TERM = NO 

value: any valid macro keyword specification. 



The parameters are explained as follows: 

exit addr 



specifies the address of an ESTAE exit routine to be entered if the task issuing this macro 
instruction terminates abnormally. If is specified, the most recent ESTAE exit is 
canceled. 



< 
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) 



# 



,CT 
,OV 

specifies the creation of a new ESTAE exit (CT) or indicates that parameters passed in 
this ESTAE macro instruction are to overlay the data contained in the previous ESTAE 
exit (OV). 

,PARAM = list addr 

specifies the address of a user-defined parameter list containing data to be used by the 
ESTAE exit routine when it is scheduled for execution. 

,XCTL = NO 
,XCTL = YES 

specifies that the ESTAE macro instruction will be canceled (NO) or will not be canceled 
(YES) if an XCTL macro instruction is issued by this program. 

,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 

specifies that all outstanding requests for I/O operations will not be saved when the 
ESTAE exit is taken (HALT), that I/O processing will be allowed to continue normally 
when the ESTAE exit is taken (NONE), or that all outstanding requests for I/O 
operations will be saved when the ESTAE exit is taken (QUIESCE). If QUIESCE is 
specified, the user's retry routine can restore the outstanding I/O requests. 

Note: If PURGE = NONE is specified, all control blocks affected by input/output 
processing may continue to change during ESTAE exit routine processing. 

If PURGE = NONE is specified and the ABEND was originally scheduled because of an 
error in input/output processing, an ABEND recursion will develop when an input/output 
interruption occurs, even if the exit routine is in progress. Thus, it will appear that the 
exit routine failed when, in reality, input/output processing was the cause of the failure. 

Do not use PURGE = HALT to stop processing a data set if you expect to continue 
reading the data set at a different point. 

ISAM Notes: If ISAM is being used and PURGE = HALT is specified or PURGE = QUIESCE 
is specified but I/O is not restored: 

• Only the input/output event on which the purge is done will be posted. Subsequent event 
control blocks (ECBs) will not be posted. 

• The ISAM check routine will treat purged I/O as normal I/O. 

• Part of the data set may be destroyed if the data set is being updated or added to when the 
failure occurred. 

,ASYNCH = YES 
,ASYNCH = NO 

specifies that asynchronous exit processing will be allowed (YES) or prohibited (NO) 
while the user's ESTAE exit is executing. 



ESTAE — Extended Specify Task Abnormal Exit 189 



ASYNCH = YES must be coded if: 

• Any supervisor services that require asynchronous interruptions to complete their 
normal processing are going to be requested by the ESTAE exit routine. 

• PURGE = QUIESCE is specified for any access method that requires asynchronous 
interruptions to complete normal input/output processing. 

• PURGE = NONE is specified and the CHECK macro instruction is issued in the 
ESTAE exit routine for any access method that requires asynchronous interruptions 
to complete normal input/output processing. 

Note: If ASYNCH = YES is specified and the ABEND was originally scheduled because 
of an error in asynchronous exit handling, an ABEND recursion will develop when an 
asynchronous exit handling was the cause of the failure. 

,TERM = NO 
,TERM = YES 

specifies that the exit routine associated with the ESTAE request will be scheduled (YES) 
or will not be scheduled (NO), in addition to normal ESTAE processing, in the following 
situations: 

• Cancel by operator. 

• Forced logoff. 

• Expiration of job step timer. 

• Exceeding of wait time limit for job step. 

• ABEND condition because of DETACH of an incomplete subtask when the STAE 
option was not specified on the DETACH. 

• ABEND of the attaching task when the ESTAE macro instruction was issued by a 
subtask. 

• ABEND of job step task when a non-job step task requested ABEND with the STEP 
option. 

When the exit routine is entered because of one of the preceding reasons, retry will not be 
permitted. If dump is requested at the time of ABEND, it is taken prior to entry into the 
exits. 

Note: If DETACH was issued with the STAE parameter, the following will occur for the task 
to be detached: 

• All ESTAE exits will be entered. 

• The most recently established STAE exit will be entered. 

• All STAI/ESTAI exits will be entered unless return code 16 is returned from one of the 
STAI exits. 

In these cases, entry to the exit is prior to dumping and retry will not be permitted. 
190 Supervisor Services and Macro Instructions 



< 



,RELATED = va/we 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

DEFESTAE ESTAE ( 4 ) , CT , PARAM= ( 2 ) , RELATED= ( DELESTAE , 
' DELETE ESTAE ' ) 



DELESTAE ESTAE , RELATED= ( DEFESTAE , ' DEFINE ESTAE ' ) 

Note: This macro instruction will fit on one line when coded, so there is no need for a 
continuation indicator. 



) 



Control is returned to the instruction following the ESTAE macro instruction. When control is 
returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 

00 

04 

0C 

10 

14 



Meaning 

Successful completion of ESTAE request. 

ESTAE OV was specified with a valid exit address, but the current exit is either nonexistent, not owned 
by the user's RB, or is not an ESTAE exit. 

Cancel (an exit address equal to zero) was specified and either there are no exits for this TCB, the most 
recent exit is not owned by the caller, or the most recent exit is not as ESTAE exit. 

An unexpected error was encountered while processing this request. 

ESTAE was unable to obtain storage for an SCB. 



Example 1 



Example 2 



Operation: Request an overlay of the existing ESTAE recovery exit (at ADDR), with the 
following options: parameter list is as PLIST, I/O will be halted, no asynchronous exits will be 
taken, ownership will be transferred to the new request block resulting from any XCTL macro 
instructions. 

ESTAE ADDR , OV , PARAM=PLIST , XCTL=YES , PURGE=HALT , ASYNCH=NO 



) 



Operation: Provide the pointer to the recovery code in the register called EXITPTR, and the 
address of the ESTAE exit parameter list in register 9. Register 8 points to the area where the 
ESTAE parameter list (created with the MF = L option) was moved. 

ESTAE (EXITPTR) ,PARAM=(9) ,MF=(E, (8) ) 
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ESTAE (List Form) 



The list form of the ESTAE macro instruction is used to construct a remote control program 
parameter list. 

The list form of the ESTAE macro instruction is written as follows: 



name 
b 

ESTAE 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede ESTAE. 

One or more blanks must follow ESTAE. 



exit addr 


,PARAM = list addr 

,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 

,ASYNCH = YES 
,ASYNCH = NO 

,TERM = NO 
,TERM = YES 

,RELATED = v«/we 
,MF = L 



exit addr: A-type address. 

list addr: A-type address. 
Default: PURGE = NONE 



Default: ASYNCH = YES 
Default: TERM = NO 

value: any valid macro keyword specification. 



The parameters are explained under the standard form of the ESTAE macro instruction, with 
the following exception: 



,MF = L 

specifies the list form of the ESTAE macro instruction. 



1.92 Supervisor Services and Macro Instructions 



ESTAE (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the ESTAE macro instruction. The control program parameter list can be generated by the 
list form of the ESTAE macro instruction. If the user desires to dynamically change the 
contents of the remote ESTAE parameter list, he may do so by coding a new exit address 
and/or a new parameter list address. If exit address or PARAM is coded, only the associated 
field in the remote ESTAE parameter list will be changed. The other field will remain as it was 
before the current ESTAE request was made. 

The execute form of the ESTAE macro instruction is written as follows: 



name 
b 

ESTAE 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede ESTAE. 

One or more blanks must follow ESTAE. 



exit addr 


,CT 
,CV 

,PARAM = list addr 



exit addr: RX-type address, or register (2) - (12). 



list addr: RX-type address, or register (2) - (12). 






,XCTL = NO 
,XCTL = YES 

,PURGE = NONE 
,PURGE = QUIESCE 
,PURGE = HALT 

,ASYNCH = YES 
,ASYNCH = NO 

/TERM = NO 
TERM = YES 



,RELATED = va/we 

,MF=(E,dr;fl#) 



value: any valid macro keyword specification. 

Ctrl addr: RX-type address, or register (1) or (2) - (12). 



) 



The parameters are explained under the standard form of the ESTAE macro instruction, with 
the following exception: 

,M$ = (E,ctrladdr) 

specifies the execute form of the ESTAE macro instruction using a remote control 
program parameter list. 
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EVENTS — Wait for One or More Events to Complete 

This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of ^ 

the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The EVENTS macro instruction is a functional specialization of the WAIT ECBLIST = macro 
facility with the advantages of notifying the program that events have completed and the order 
in which they completed. 

The macro performs the following functions: 

• Creates and deletes EVENTS tables. 

• Initializes and maintains a list of completed event control blocks. 

• Provides for single or multiple ECB processing. 

For a detailed explanation of how to use EVENTS to perform these functions see "Using the 
EVENTS Macro Instruction" in this section. 

The EVENTS macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 4 

b One or more blanks must precede EVENTS. l 

EVENTS 

b One or more blanks must follow EVENTS. 

ENTRIES = « n: variable, decimal digit 1-32,767. 

ENTRIES = DEL,TABLE = table address table address: symbol, RX-type address, or register (2) - (12). 
TABLE = table address Note: If ENTRIES = n or ENTRIES = DEL, TABLE = table address is not 

specified, no other parameter should be specified. 

,WAIT = NO Default: None. 

,WAIT = YES 

,ECB = ecb address ecb address: symbol, RX-type address, or register (2) - (12). 

,LAST = last address last address: symbol, RX-type address, or register (2) - (12). 

Note: Optional parameters are only valid when TABLE = table address is the 

only required parameter specified. 

The parameters are explained as follows: 

ENTRIES = « 

n is a decimal number from 1 to 32,767 that specifies the maximum number of completed 
ECB addresses that can be processed in an EVENTS table concurrently. 

Note: When this parameter is specified no other parameter should be specified. 

ENTRIES - DEL,TABLE = table address 

specifies that the EVENTS table whose address is specified by TABLE = table address is 

to be deleted. The user is responsible for deleting all of the tables he creates; however, all m 

existing tables are automatically freed at task termination. ^ 
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Notes: 

1. When this parameter is specified no other parameter should be specified. 

2. table address specifies a storage location below 16 megabytes. 

TABLE = table address 

specifies either a register number or the address of a word containing the address of the 
EVENTS table associated with the request. The address specified with the operand 
TABLE must be that of an EVENTS table created by this task. 

Note: table address specifies a storage location below 16 megabytes. 

,WATT = NO 
,WAIT = YES 

specifies whether or not to put the issuing program in a wait state when there are no 
completed events in the* EVENTS table (specified by the TABLE = parameter). 

,ECB = ecb address 

specifies either a register number or the address of a word containing the address of an 
event control block. The EVENTS macro instruction should be used to initialize any 
event-type ECB. To avoid the accidental destruction of bit settings by a system service 
such as an access method, the ECB should be initialized after the system service that will 
post the ECB has been initiated (thus making the ECB eligible for posting) and before the 
EVENTS macro is issued to wait on the EVENTS table. 

Notes: 

1. Register 1 should not be specified for the ECB address. 

2. This parameter may not be specified with the LAST= parameter. 

3. If only ECB initialization is being requested, neither WAIT=NO nor WAIT= YES 
should be specified, to prevent any unnecessary WAIT processing from occurring. 

,LAST = last address 

specifies either a register number or the address of a word containing the address of the 
last EVENT parameter list entry processed. 

Notes: 

1. Register 1 should not be specified for the LAST address. 

2. This parameter should not be specified with the ECB= parameter. 

3. last address specifies a storage location below 16 megabytes. 



) 
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Using the EVENTS Macro Instruction 

The following explains the different uses of EVENTS: 

• Creating EVENTS Tables — When ENTRIES = n is specified, the system creates an 

EVENTS table with "n" entries for completed ECB addresses. This table is queued on the 
EVENTS table queue associated with the task. (There is no limit to the number of 
EVENTS tables that can be queued for a single task.) The address of the EVENTS table is 
returned to the user in register 1. See Figure 54. 
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ENTRY1 
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ENTRYn-1 
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Figure 54. Creating a Table 

• Deleting EVENTS Tables - When ENTRIES = DEL,TABLE = table address is specified, 
the EVENTS table whose address is specified by the TABLE = table address parameter shall 
be deleted. The address specified with the TABLE operand must be that of an EVENTS 
table created by this task. The user is responsible for deleting all of the tables he creates; 
however, all existing tables are automatically freed at task termination. 

• Initializing ECBs — When an ECB is created, bits (wait bit) and bit 1 (post bit) must be 
set to zero. When an EVENTS ECB = macro instruction is issued, bit of the associated 
event control block is set to 1. When a POST macro instruction is issued, bit 1 of the 
associated event control block is set to 1 and bit is set to 0. If the ECB is reused, bit 
and bit 1 must be set to zero before either a WAIT, EVENTS ECB = , or POST macro 
instruction can be specified. If, however, the bits are set to zero before the ECB has been 
posted, any task waiting for that ECB to be posted will remain in wait state. 

• Maintaining a List of Completed EVENT Control Blocks — After the ECB has been 
initialized the POST macro sets the complete bit and puts the address of the completed 
ECB in the EVENTS table. 



« 
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• Providing Single or Multiple ECB Processing — When the WAIT parameter is specified and 
there are completed ECBs in the EVENTS table, the address of the parameter list is 
returned in register 1. The parameter list has the following format: 
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w ECBm 















Figure 55. Parameter List Format 



) 



The parameter list contains completed ECB addresses in post occurrence order. The high order 
bit of the last word in the list is set to 1 . The user may choose to process the entire list (see 
LAST parameter) or one event at a time by successive EVENTS requests with the WAIT = 
option. 



rJm 



However, if WAIT = NO is specified and no ECBs are posted in the EVENTS table, register 1 
contains a zero when the user receives control. 

When a user has processed more than one ECB in the parameter list returned from the previous 
EVENTS WAIT = macro, the LAST = parameter should be used to indicate the last ECB 
processed. The EVENTS macro removes from the parameter list all entries from the first thru 
the last specified by LAST, and then completes processing the request according to the WAIT = 
specification. 

In the illustration that follows, ECBs 6 through 10 were posted to the parameter list while the 
user was processing 1 through 5. 
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EVENTS TABLE-table address, WAIT=YES 
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Figure 56. Posting the Parameter List 
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This figure demonstrates processing one event at a time. 



) 



Issuing EVENTS TABLE=table address, WAIT=YES for the 
first time will initiate: 
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Figure 57. Processing One Event At a Time 
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Example 1 



The following shows total processing via EVENTS. 



EVENTS and ECB Initialization 



START 




EVENTS 


ENTRIES=1000 


ST 


Rl, TAB ADD 


WRITE 


ECBA 


LA 


R2,ECBA 


EVENTS 


TABLE=TABADD , ECB= ( R2 ) 



Parameter List Processing 



L00P1 
L00P2 



BEGIN 

EVENTS 

LR 

B 

EVENTS 

LR 

EQU 

TM 

BO 

LA 

B 



TABLE=TABADD , WAIT=YES 

R3,R1 PARMLIST ADDR 

L00P2 GO TO PROCESS ECB 

TABLE-TABADD , WAIT=YES , LAST= ( R3 ) 

R3,R1 SAVE POINTER 

* PROCESS COMPLETED EVENTS 

CKRSKX'SO 1 TEST FOR MORE EVENTS 

LOOP1 IF NONE, GO WAIT 

R3,4(,R3) GET NEXT ENTRY 

LOOP2 GO PROCESS NEXT ENTRY 



Deleting EVENTS Table 



EVENTS 
TABADD DS 



TABLE=TABADD , ENTRIES=DEL 
F 



Example 2 



Processing One ECB at a Time. 





EVENTS 


ENTRIES=10 




ST 


1 , TABLE 


NEXTREC 


GET 


TPDATA,KEY 




ENQ 


( RESOURCE , ELEMENT , E , , SYSTEM ) 




READ 


DECBRW,KU, ,'S' ,MF=E 




LA 


3,DECBRW 




EVENTS 


TABLE=TABLE ,ECB= ( 3 ) ,WAIT=YES 




WRITE 


DECBRW,K,MF=E 




LA 


3 , DECBRW 


RETEST 


EVENTS 


TABLE =TABLE , ECB= ( 3 ) , WAIT=NO 




LTR 


1/1 




BNZ 


NEXTREC 




B 


RETEST 


TABLE 


DS 


F 
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FRACHECK — Fast Path Resource Authorization Checking 

The FRACHECK macro is used to check a user's authorization for access to a resource. 
FRACHECK verifies access to those resources whose RACF profiles have been brought into 
main storage by the RACLIST facility. FRACHECK is a branch entered service that does not 
save registers upon entry. Registers 0-5, 14, and 15 are used by the FRACHECK macro 
instruction and are not restored. Registers 6-13 are not altered by FRACHECK. 

Note: For RACF release 1.6 and previous releases: Only callers in 24-bit addressing mode can 
issue this macro. Callers executing in 31 -bit addressing mode, who want to use the 
FRACHECK function, can code the RACROUTE macro. 

The standard form of the FRACHECK macro instruction is written as follows: 



FRACHECK 

b 



name: symbol. Begin name in column 1. 

One or more blanks must precede FRACHECK. 

One or more blanks must follow FRACHECK. 



ENTITY = entity addr 

,CLASS = 'classname' 
.CLASS = classname addr 



entity addr: A-type address or register (2) - (12). 

classname: DASDVOL or TAPEVOL. 

classname addr: A-type address or register (2) - (12). 



) 



,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg: 

, ACEE = acee addr 

,WK ARE A = area addr 

,APPL= 'applname' 
, APPL = applname addr 

,INSTLN =parm list addr 
, RELEASE = number 



reg: registers (2) - (12). 
Default: ATTR = READ 



acee addr: A-type address or register (2) - (12). 
area addr: A-type address or register (2) - (12). 

applname addr: A-type address or register (2) - (12). 
parm list addr: A-type address or register (2) - (12). 

number: 1.6 or 1.7 
Default: RELEASE =1.6 



The parameters are explained as follows: 

ENTITY = entity addr 

specifies that RACF authorization checking is to be performed for the resource whose 
name is pointed to by the specified address. The resource name is a 6-byte volume serial 
number for CLASS = 'DASDVOL' or CLASS = 'TAPEVOL'. The name must be left 
justified and padded with blanks. The length of all other resource names is determined 
from the class descriptor tables. 



) 



,CLASS = 'classname ' 

,CLASS = classname addr 

specifies that RACF authorization checking is to be performed for a resource of the 
specified class. If an address is specified, the address must point to an 8-byte field 
containing the classname. 
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,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR= ALTER 

,ATTR = (reg) 

specifies the access authority required by the user or group accessing the resource: 

READ — RACF user or group can open the resource only to read. 

UPDATE — RACF user or group can open the resource to read or write. 

CONTROL — For VSAM data sets, RACF user or group has authority equivalent to 
the VSAM control password. For non-VSAM data sets and other resources, RACF 
user or group has UPDATE authority. 

ALTER — RACF user or group has total control over the resource. 

If a register is specified, the register must contain one of the following codes in the 
low-order byte of the register: 

X'02' - READ 
X'04'- UPDATE 
X'08'- CONTROL 
X'80'- ALTER 

,ACEE = acee addr 

specifies the address of the accessor control environment element (ACEE) to be used to 
check authorization and to locate the in-storage profiles (RACLIST output) for the 
specified classes. If an ACEE is specified, it is used for authorization checking. If the 
specified ACEE has an in-storage profile list for the specified class, it is used to locate the 
resource. If an ACEE is not specified or if there is no in-storage profile list for the 
specified class in the ACEE, RACF uses the TASK ACEE pointer in the extended TCB 
called the TCBSENV. Otherwise, or if the TASK ACEE pointer is zero, RACF uses the 
main ACEE to obtain the list of the in-storage profiles. The main ACEE is pointed to by 
the ASXBSENV field of the address space extension block. 

,WKAREA = area addr 

specifies the address of a 16 word work area to be used by FRACHECK which contains 
the following information: 

Word 13 contains the return code the FRACHECK caller receives. 

Word 14 contains the address of the in-storage profile used to determine 
authorization, or zero if no profile was found. 

Word 15 contains a value provided by a pre-processing installation exit, or zero if 
there was no pre-processing exit. 

Workarea words 13 and 14 are passed back to the FRACHECK issuer as a return code in 
register 15 (see return codes below) and a profile address in register 1, respectively. 



< 
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) 



, APPL = 'applname ' 

,APPL = applname addr 

specifies the name of the application requesting the authorization checking. This 
information is not used for the authorization checking process but is made available to 
the installation exit(s). If an address is specified, it should point to an 8-byte area 
containing the application name, left justified and padded with blanks, if necessary. 

JNSTLN =parm list addr 

specifies the address of an area that contains information for the FRACHECK 
installation exit. This address is passed to the exit routine when the exit is given control. 
The INSTLN parameter is used by application or installation programs to pass 
information to the FRACHECK installation exit. 

,RELEASE = number 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 58. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
FRACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

Parameters For RELEASE = 1.6 and Later 

The RELEASE values for which a specific parameter is valid are marked with an 'X'. 






Parameter 


RELEASE = 
1.6 


RELEASE = 
1.7 


ACEE = 


X 


X 


APPL = 


X 


X 


ATTR = 


X 


X 


CLASS = 


X 


X 


ENTITY = 


X 


X 


INSTLN = 


X 


X 


RELEASE = 


X 


X 


WKAREA = 


X 


X 



Figure 58. FRACHECK Parameters for RELEASE = 1.6 and Later 
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Return Codes and Reason Codes 



When control is returned, register 1 5 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 The user or group is authorized to use the resource. 

04 The resource or classname is not defined to RACF. 

08 The user or group is not authorized to use the resource. 

0C RACF is not active. 

10 FRACHECK installation exit error occurred. 

14 RACF CVT does not exist (RACF is not installed or insufficient level of RACF is installed). 

64 Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form 

of the FRACHECK macro; however, the list form of the macro does not have the proper RELEASE 
parameter. Macro processing terminates. 

FRACHECK examines the auditing and global auditing options currently in effect for the 
resource for which access authority is being determined. It sets a reason code that indicates to 
FRACHECK's caller if logging of the access attempt should be performed: 

Hexadecimal 

Code Meaning 

00 The access attempt is not within the scope of the audit or global audit specification. No logging should 

be performed. The user is either authorized or unauthorized for the resource as indicated by the 
FRACHECK return code. 

04 The access attempt is within the scope of the audit or global audit specification for that resource. 

Logging of the attempt should be performed by issuing, for example, a RACHECK for the resource for 
which authorization is being determined. RACHECK provides the necessary logging function. The user 
is either authorized or unauthorized for the resource, as indicated by the FRACHECK return code. 



< 
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FRACHECK (List Form) 



The list form of the FRACHECK macro instruction is written as follows: 



FRACHECK 

b 



name: symbol. Begin name in column 1 . 

One or more blanks must precede FRACHECK. 

One or more blanks must follow FRACHECK. 



ENTITY = entity addr 

,CLASS= 'classname' 
,CLASS = classname addr 



entity addr: A-type address. 

classname: DASDVOL or TAPEVOL. 
classname addr: A-type address. 



) 



) 



,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 

,ACEE = acee addr 

,WKAREA = area addr 

,APPL= 'applname' 
,APPL = applname addr 

,INSTLN =parm list addr 
, RELEASE = number 



Default: ATTR = READ 



acee addr: A-type address. 
area addr: A-type address. 

applname addr: A-type address. 
parm list addr: A-type address. 

number: 1.6 or 1.7 
Default: RELEASE =1.6 



,MF = L 



The parameters are explained under the standard form of the FRACHECK macro instruction, 
with the following exception: 



,MF = L 

specifies the list form of the FRACHECK macro instruction. 
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FRACHECK (Execute Form) 

The execute form of the FRACHECK macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede FRACHECK. 
FRACHECK 

b One or more blanks must follow FRACHECK. 

ENTITY = entity addr entity addr: RX-type address or register (2) - (12). 

,CLASS = classname addr classname addr: RX-type address or register (2) - (12). 

,ATTR = (reg) reg: register (2) - (12). 

,ACEE = acee addr acee addr: RX-type address or register (2) - (12). 

,WKAREA = area addr area addr: RX-type address or register (2) - (12). 

,APPL = applname addr applname addr: RX-type address or register (2) - (12). 

,INSTLN -parm list addr parm list addr: RX-type address or register (2) - (12). 

,RELEASE = (number, CHECK) number: 1 .6 or 1 .7 

,RELEASE = number Default: RELEASE = 1 .6 
,RELEASE = (,CHECK) 

,MF = (E,ctrl addr) Ctrl addr: RX-type address or register (1) - (12). 



The parameters are explained under the standard form of the FRACHECK macro instruction, 
with the following exception: 

specifies the execute form of the FRACHECK macro instruction, using a remote control 
program parameter list. 

,RELEASE = (number,CHECK) 
.RELEASE = m//nfo?r 
.RELEASE = (.CHECK) 

specifies the RACF release level of the parameter list to be generated by the is macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 58 on page 203. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
FRACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute 
form of the macro, the execute form of the macro will not be done. Instead, a return 
code of X'64' will be generated. 
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FREEMAIN - Free Virtual Storage 



The FREEMAIN macro instruction releases one or more areas of virtual storage, or an entire 
virtual storage subpool, previously assigned to the active task as a result of a GETMAIN 
macro instruction. The active task is abnormally terminated if the specified virtual storage does 
not start on a doubleword boundary or, for an unconditional request, if the specified area or 
subpool is not currently allocated to the active task. Register 1 5 is set to to indicate 
successful completion. For a conditional FREEMAIN, register 15 is set to 4 if the specified 
area or subpool is not currently allocated to the active task. 

In the parameters discussed below, EU, LU, and VU specify unconditional requests and result 
in the same processing as E, L, and V, respectively. The two formats for these requests are 
available to maintain compatibility with the GETMAIN formats. 

The standard form of the FREEMAIN macro instruction is written as follows: 






FREEMAIN 
b 



name: symbol. Begin name in column 1 . 

One or more blanks must precede FREEMAIN. 

One or more blanks must follow FREEMAIN. 



) 



LC,LA = length addr 

LU,LA = length addr 

L,LA = length addr 

VC 

VU 

V 

EC,LV = length value 

EU,LV = length value 

E,LV = length value 

RC,LV = length value 

RC,SP = subpool nmbr 

RU,LV = length value 

RU,SP = subpool nmbr 

R,LV = length value 

R,SP = subpool nmbr 

, A = addr 

,SP = subpool nmbr 
,RELATED = value 



length addr: A-type address, or register (2) - (12). 

length value: symbol, decimal digit, or register (2) - (12). If R, RC, 

or RU is specified, register (0) may also be specified. 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 

If R is specified, register (0) may also be specified. 

Note: For subpool freemains, if the forms RC,SP = subpool nmbr or 

RU ,SP = subpool nmbr or R,SP = subpool nmbr are specified, no other 

parameters except RELATED may be specified. SP = must be specified 

for subpool FREEMAINS; for other types of FREEMAIN, SP= is optional 

and defaults to SP = 0. 

Note: RC and RU are the only parameters that can be used to free 

storage above 16 Mb. 



addr: A-type address, or register (2) - (12). 

Note: If R, RC, or RU is coded, register (1) can also be specified. 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). If R is 
specified above, register (0) may also be specified. 

value: any valid macro keyword specification. 
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The parameters are explained as follows: 

LC,LA = length addr ' 

LU,LA = length addr 
L,LA = length addr 
VC 

vu 

V 

EC,LV = length value 
EU,LV = length value 
E,LV = length value 
RC,LV = length value 
RC,SP = subpool nmbr 
RU,LV = length value 
RU,SP = subpool nmbr 
R,LV ' = length value 
R,SP = subpool nmbr 

specifies the type of FREEMAIN request: 

LC, LU, and L indicate conditional (LC) and unconditional (LU and L) list requests, and 
specify release of one or more areas of virtual storage. The length of each virtual storage 
area is indicated by the values in a list beginning at the address specified in the LA 
parameter. The address of each of the virtual storage areas must be provided in a 
corresponding list whose address is specified in the A parameter. All virtual storage areas 
must start on a doubleword boundary. 

VC, VU, and V indicate conditional (VC) and unconditional (VU and V) variable a 

requests, and specify release of single areas of virtual storage. The address and length of \ 

the virtual storage area are provided at the address specified in the A parameter. 

EC, EU, and E indicate conditional (EC) and unconditional (EU and E) element requests, 
and specify release of single areas of virtual storage. The length of the single virtual 
storage area is indicated in the LV parameter. The address of the virtual storage area is 
provided at the address indicated in the A parameter. 

RC, RU, and R indicate conditional (RC) and unconditional (RU and R) register 
requests, and specify release of single areas of virtual storage from the subpool indicated, 
or specify release of the entire subpool indicated. If the release is not for the entire 
subpool, the address of the virtual storage area is indicated in the A parameter. The 
length of the area is indicated in the LV parameter. The virtual storage area must start 
on a doubleword boundary. 

Notes: 

1. A conditional request indicates that the task is not to be abnormally terminated if the 
virtual storage being freed is not allocated to the active task. However, A05-2 and 
A78-2 abends cannot be prevented. An unconditional request indicates that the task is 
to be abnormally terminated in this situation. 

2. If the address of the area to be freed is greater than 16 Mb, you must use RC or RU. 

3. Callers executing in either 24-bit or 31 -bit addressing mode can use RC or RU to free . 
storage located above 16 Mb. ■ 
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) 



LA specifies the virtual storage address of one or more consecutive fullwords starting on a 
fullword boundary. One word is required for each virtual storage area to be released; the 
high-order bit in the last word must be set to 1 to indicate the end of the list. Each word 
must contain the required length in the low-order three bytes. The fullwords in this list 
must correspond with the fullwords in the associated list specified in the A parameter. 
The words should not reside in the area to be released. If this rule is violated and if the 
words are the last allocated items on a virtual page, the whole page is returned to storage 
and the FREEMAIN abends with an 0C4. The words must not overlap the virtual 
storage area specified in the A parameter. 

LV specifies the length, in bytes, of the virtual storage area being released. The value 
should be a multiple of 8; if it is not, the control program uses the next high multiple of 
8. If R is coded, LV = (0) may be designated; the high-order byte of register must 
contain the subpool number, and the low-order three bytes must contain the length (in 
this case, the SP parameter is invalid). 

, A = addr 

specifies the virtual storage address of one or more consecutive fullwords, starting on a 
fullword boundary. The words should not reside within the area to be released. If this 
rule is violated and if the words are the last allocated items on a virtual page, the whole 
page is returned to storage and the FREEMAIN abends with an 0C4. If E, EC, EU, R, 
RC, or RU is designated, one word, which contains the address of the virtual storage area 
to be released, is required. If V, VC, or VU is coded, two words are required; the first 
word contains the address of the virtual storage area to be released, and the second word 
contains the length of the area. If L, LC, or LU is coded, one word is required for each 
virtual storage area to be released; each word contains the address of one virtual storage 
area. If R, RC, or RU is coded, any of the registers 1 through 12 can be designated, in 
which case the address of the virtual storage area, not the address of the fullword, must 
have previously been loaded into the register. 

,SP ~ subpool nmbr 

specifies the subpool number of the virtual area to be released. The subpool number can 
be between and 127. The SP parameter is optional and if omitted, subpool is 
assumed. If R is coded, SP = (0) can be designated, in which case the subpool number 
must be previously loaded into the low-order byte of register 0. 

For subpool freemains, the SP parameter specifies the number of the subpool to be 
released and the valid range is 1 through 127. Subpool zero cannot be released. If 
R,SP = (0) is specified with no other parameters, the high-order byte of register must 
contain the subpool number and the low-order 3 bytes must contain zero. 

,RELATED = va/we 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 



^ 
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The RELATED parameter may be used, for example, as follows: 

GET1 GETMAIN R,LV=4096 ,RELATED= (FREE1 , 

• GET STORAGE ' ) 



FREE1 FREEMAIN 



R,LV=4096,A=(1) , 

RELATED= ( GET1 ' FREE STORAGE • ) 



Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Virtual storage was freed. 

04 Not all virtual storage was freed. 



Example 1 



Operation: Free 400 bytes of storage from subpool 10, where the storage address is contained 
in register 1. If the storage was allocated to the task, register 15 will contain on return; if the 
storage was not allocated to the task or was partially free, the status of the storage remains 
unchanged, and a 4 is returned in register 15. 



FREEMAIN 



RC,LV=400,A=(1) ,SP=10 



Example 2 



Operation: Free all of subpool 3 (if any) that belongs to the current task. A return will be 
made to the caller even if there is no subpool 3 for the current task. 



FREEMAIN 



RU f SP=3 



Example 3 



Operation: Free from subpool 5 three areas of lengths 200, 800, and 32 previously obtained by 
a list type GETMAIN which placed the addresses in AREADD. If any of these areas are not 
allocated to the task, the task will be abnormally terminated. 



FREEMAIN 



LU , LA=LNTHLIST , A=AREAADD , SP=5 



LNTHLIST DC F • 200 ' ,F ' 800 ■ ,X • 80 ' , FL3 ' 32 » 
AREAADD DS 3F 



( 
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FREEMAIN (List Form) 



Use the list form of the FREEMAIN macro instruction to construct a nonexecutable control 
program parameter list. 

The list form of the FREEMAIN macro instruction is written as follows: 



FREEMAIN 

b 



name: symbol. Begin name in column 1. 

One or more blanks must precede FREEMAIN. 

One or more blanks must follow FREEMAIN. 



) 



LC 

LU 

L 

VC 

VU 

V 

EC 

EU 

E 

,LA = length addr 
,LV = length value 



,A = addr 

,SP = subpool nmbr 
.RELATED = value 
,MF = L 



length addr: A-type address. 

length value: symbol or decimal digit. 

Note: LA may only be specified with. LC, LU, or L above. 

Note: LV may only be specified with EC, EU, or E above. 

addr: A-type address. 

subpool nmbr: symbol or decimal digit 0-127. 

value: any valid macro keyword specified. 



) 



The parameters are explained under the standard form of the FREEMAIN macro instruction, 
with the following exception: 

,MF = L 

specifies the list form of the FREEMAIN macro instruction. 
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FREEMAIN (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the FREEMAIN macro instruction. The parameter list can be generated by the list form of 
either a GETMAIN or a FREEMAIN. 

The execute form the the FREEMAIN macro instruction is written as follows: 



b 

FREEMAIN 

b 



name: symbol. Begin name in column 1 . 

One or more blanks must precede FREEMAIN. 

One or more blanks must follow FREEMAIN. 



LC 
LU 
L 
VC 

vu 

V 
EC 

EU 
E 

,LA = length addr 
,LV = length value 

, A = addr 

,SP = subpool nmbr 
,RELATED = va/ue 
,MF = (E,ctrl prog) 



length addr: RX-type address or register (2) - (12). 
length value: symbol, decimal digit, or register (2) - (12). 
Note: LA may only be specified with LC, LU, or L above. 
Note: LV may only be specified with EC, EU, or E above. 



addr: RX-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 

value: any valid macro keyword specified. 

Ctrl prog: RX-type address, or register (1) or (2). 



The parameters are explained under the standard form of the FREEMAIN macro instruction, 
with the following exception: 

,MF = (E,cfr7/?rog) 

specifies the execute form of the FREEMAIN macro instruction using a remote control 
program parameter list. 



< 
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GETMAIN — Allocate Virtual Storage 



The GETMAIN macro instruction requests the control program to allocate one or more areas 
of virtual storage to the active task. The virtual storage areas are allocated from the specified 
subpool in the virtual storage area assigned to the associated job step. The virtual storage areas 
each begin on a doubleword or page boundary and are not cleared to when allocated. (The 
storage is set to zero for the initial allocation of a page.) The total of the lengths specified must 
not exceed the length available. For most subpools the storage will be released when the task 
assigned ownership terminates, or through the use of the FREEMAIN macro instructions. 

The options R, LC, LU, VC, VU, EC, or EU can be used by callers in either 24-bit or 31 -bit 
addressing mode. If one of these options is specified, storage area addresses and lengths will be 
treated as 24-bit addresses and values. The parameter list addresses and the pointers to the 
length and address lists in the parameter lists (if present) will be treated as 31 -bit addresses if 
the caller's addressing mode is 31 -bit; otherwise, they will be treated as 24-bit addresses. 

The options RU, RC, VRU, and VRC can be used by callers in either 24-bit or 31 -bit 
addressing mode. However, all values and addresses will be treated as 31 -bit values and 
addresses. 

The standard form of the GETMAIN macro instruction is written as follows: 



) 



GETMAIN 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede GETMAIN. 

One or more blanks must follow GETMAIN. 



LC,LA = length addr,A = addr 
LU,LA = length addr, A = addr 
VC,LA = length addr, A = addr 
VU,LA = length addr, A = addr 
EC,LV = length value,A = addr 
EU,LV = length value,A = addr 
RC,LV = length value 
RU,LV = length value 
R,LV = length value 
VRC,LV = {maximum length value, 
minimum length value) 
VRU,LV = {maximum length value, 
minimum length value 

,SP = subpool nmbr 



,BNDRY = DBLWD 
,BNDRY = PAGE 



length addr: A-type address, or register (2) - (12). 

length value: symbol, decimal digit, or register (2) - (12). If R is 

specified, register (0) may also be specified. 

addr: A-type address, or register (2) - (12). 

Note: RC, RU, VRC, or VRU must be used to allocate storage with 

addresses greater than 16Mb. 



maximum length value: symbol, decimal, digit, or register (2) - (12). 
minimum length value: symbol, decimal, digit, or register (2) - (12). 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 
Note: Subpools are specified as follows: 

• LC,LU,VC,VU,EC,EU,RC,RU,VRC, and VRU use the SP parameter. 

• R with LV not equal to (0) uses the SP parameter. 

• R with LV = (0) must use register 0. The low-order three bytes of register 
must contain the length of the subpool, and the high-order byte must 
contain the number of the subpool. 

Default: BNDRY = DBLWD 

Note: This parameter may not be specified with R above. 



) 



,LOC = BELOW 
,LOC = (BELOW,ANY) 

,LOC = (ANY) 
,LOC = (ANY,ANY) 
,LOC = RES 
,LOC = (RES,ANY) 

,RELATED = value 



Default: LOC = RES 

Note: This parameter can only be used with RC, RU, VRC, or VRU. 

On all other forms, the default, LOC = BELOW is used. 



value: any valid macro keyword specification. 
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The parameters are explained as follows: 

LC,LA = length addr, A = addr 
LU,LA = length addr, A = addr 
VC,LA = length addr, A = addr 
VU,LA = length addr, A = addr 
EC,LV = length value, A = addr 
EU,LV ■* length value, A — addr 
RC,LV = length value 
RU,LV = length value 
R,LV = length value 

VRC,LV = (maximum length value^ minimum length value) 
VRU,LV = (maximum length value^ minimum length value) 
specifies the type of GETMAIN request: 

LC and LU indicate conditional (LC) and unconditional (LU) list requests and specify 
requests for one or more areas of virtual storage. The length of each virtual storage area 
is indicated by the values in a list beginning at the address specified in the LA parameter. 
The address of each of the virtual storage areas is returned in a list beginning at the 
address specified in the A parameter. No virtual storage is allocated unless all of the 
requests in the list can be satisfied. 

VC and VU indicate conditional (VC) and unconditional (VU) variable requests and 
specify requests for single areas of virtual storage. The length of the single virtual storage 
area is between the two values at the address specified in the LA parameter. The address 
and actual length of the allocated virtual storage area are returned by the control program 
at the address indicated in the A parameter. 

EC and EU indicate conditional (EC) and unconditional (EU) element requests, and 
specify requests for single areas of virtual storage. The length of the single virtual storage 
area is indicated in the LV = length value parameter. The address of the allocated virtual 
storage area is returned at the address indicated in the A parameter. 

RC indicates a conditional register request, and R and RU indicate unconditional register 
requests. RC, RU, and R specify requests for single areas of virtual storage. The length 
of the single virtual area is indicated in the LV — length value parameter. The address of 
the allocated virtual storage area is returned in register 1. (R generates the SVC 10 
calling sequence, whereas RU and RC generate the SVC 120 and associated parameter 
format.) 

VRC and VRU indicate variable register conditional (VRC) and unconditional (VRU) 
requests for a single area of virtual storage. The length returned will be between the 
maximum and minimum lengths specified by the parameter LV ' = (maximum length value, 
minimum length value). The address of the allocated virtual storage is returned in register 
1 and the length in register 0. 

Notes: 

1. A conditional request indicates that the task is not to be abnormally terminated if virtual 
storage is not allocated to the active task. An unconditional request indicates that the 
task is to be abnormally terminated in this situation. 

2. The LC, LU, VC, VU, EC, EU, and R forms of the GETMAIN macro instruction can 
only be used to obtain virtual storage with addresses below 16 Mb. The RC, RU, VRC, 
and VRU forms of the GETMAIN macro instruction can be used to obtain virtual 
storage when the addresses are above 16 Mb or when the addresses are below 16Mb. 
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LA specifies the virtual storage address of consecutive fullwords starting on a fullword 
boundary. Each fullword must contain the required length in the low-order three bytes, 
with the high-order byte set to 0. The lengths should be multiples of 8; if they are not, 
the control program uses the next higher multiple of 8. If VC or VU was coded, two 
words are required. The first word contains the minimum length required, the second 
word contains the maximum length. If LC or LU was coded, one word is required for 
each virtual storage area requested; the high-order bit of the last word must be set to 1 to 
indicate the end of the list. The list must not overlap the virtual storage area specified in 
the A parameter. 

LV = length value specifies the length, in bytes, of the requested virtual storage. The 
number should be a multiple of 8; if it is not, the control program uses the next higher 
multiple of 8. If R is specified, LV = (0) may be coded; the low-order three bytes of 
register must contain the length, and the high-order byte must contain the subpool 
number. LV = (maximum length value, minimum length value) specifies the maximum and 
minimum values of the length of the storage request. 

A specifies the virtual storage address of consecutive fullwords, starting on a fullword 
boundary. The control program places the address of the virtual storage area allocated in 
one or more words. If E was coded, one word is required. If L was coded, one word is 
required for each entry in the LA list. If V was coded, two words are required. The first 
word contains the address of the virtual storage area, and the second word contains the 
length actually allocated. The list must not overlap the virtual storage area specified in 
the LA parameter. 

,SP = subpool nmbr 

specifies the number of the subpool from which the virtual storage area is to be allocated. 
The subpool number must be a valid subpool number between and 127. 

,BNDRY = DBLWD 
,BNDRY = PAGE 

specifies that alignment on a doubleword boundary (DBLWD) or alignment with the start 
of a virtual page on a 4K boundary (PAGE) is required for the start of a requested area. 
If one of the following subpools 226, 233-235, 239, 245, or 253-255 is requested, the 
BNDRY = PAGE keyword is ignored. Requests for storage from these subpools are 
assigned from a single page, unless the request is greater than a page. 

,LOC = BELOW 

,LOC = (BELOW,ANY) 

,LOC = ANY 

,LOC = (ANY,ANY) 

,LOC = RES 

,LOC = (RES,ANY) 

specifies the location of virtual and real storage. When LOC is specified, real storage is 
allocated anywhere until the storage is fixed. After the storage is fixed, virtual and real 
storage are located in the following manner. 

LOC = BELOW indicates that real and virtual storage are to be located below 16 Mb. 

LOC = (BELOW, ANY) indicates that virtual storage is to be located below 16 Mb and 
real storage can be located anywhere. 

LOC = ANY and LOC = (ANY, ANY) indicates that virtual and real storage can be 
located anywhere. 
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Note: The LOC parameter is not valid for fixed subpools. For fixed subpools the actual 
location of the virtual storage area depends on the subpool specified. If the subpool is 
supported (backed) above 16 megabytes, GETMAIN attempts to locate the virtual 
storage area above 16 megabytes. If this is not possible, GETMAIN locates the virtual 
storage below 16 megabytes. LSQA subpools will be backed anywhere regardless of the 
LOC parameter. 

LOC = RES indicates that the location of virtual and real storage depends on the location 
of the caller. If the caller resides below 16 Mb, virtual and real storage are to be located 
below 16 Mb; if the caller resides above 16 Mb, virtual and real storage are to be located 
anywhere. 

LOC = (RES,ANY) indicates that the location of virtual storage depends upon the 
location of the caller. If the caller resides below 16 Mb, virtual storage is to be located 
below 16 Mb; if the caller resides above 16 Mb, virtual storage can be located anywhere. 
In either case, real storage can be located anywhere. 

,RELATED = va/we 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

GET1 GETMAIN R,LV=4096 ,RELATED= (FREE1 , 

1 GET STORAGE * ) 



FREE1 FREEMAIN R,LV=4096 , A= ( 1) ,RELATED= (GET1 , 

1 FREE STORAGE ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

When control is returned, for conditional type requests (LC, EC, VC, RC, and VRC) register 
15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Virtual storage requested was allocated. 

04 The request could not be satisfied because of insufficient virtual storage. 

The contents of registers 0, 1, and 15 are not preserved when the GETMAIN macro instruction 
is issued. 



( 
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Example 1 

Operation: Obtain 400 bytes of storage from subpool 10. If the storage is available, the 
address will be returned in register 1 and register 15 will contain 0; if virtual storage is not 
available, register 1 5 will contain 4. 

GETMAIN RC,LV=400,SP=10 

Example 2 

Operation: Obtain 48 bytes of storage from default subpool 0. If the storage is available, the 
address will be stored in the word at AREAADDR; if the virtual storage is not available, the 
task will be abnormally terminated. 

GETMAIN EU, LV= 4 8, A= AREAADDR 



AREAADDR DS F 

Example 3 

Operation: Obtain a maximum of 4096 or a minimum of 1024 bytes of virtual storage, with 
addresses above or below 16 Mb. Indicate that if the real storage is fixed, it should also be 
located above or below 16 Mb. If the storage is available, the address will be returned in 
register 1 and the length of the storage allocated will be returned in register 0; if the storage is 
not available, the task will be terminated. 

GETMAIN VRU,LV=(4096,1024) ,LOC=ANY 



) 
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GETMAIN (List Form) 



Use the list form of the GETMAIN macro instruction to construct a control program 
parameter list. 

The list form of the GETMAIN macro instruction is written as follows: 



GETMAIN 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede GETMAIN. 

One or more blanks must follow GETMAIN. 



LC 
LU 
VC 
VU 
EC 
EU 

,LA = length addr 
,LV = length value 



, A = addr 

,SP = subpool nmbr 

,BNDRY = DBLWD 
,BNDRY = PAGE 

.RELATED = value 

,MF = L 



length addr: A-type address. 

length value: symbol or decimal digit. 

Note: LA may only be specified with EC or EU above. 

Note: LV may only be specified with LC, LU, or VU above. 

addr: A-type address. 

subpool nmbr: symbol or decimal digit 0-127. 

Default: BNDRY = DBLWD 

value: any valid macro keyword specified. 



The parameters are explained under the standard form of the GETMAIN macro instruction, 
with the following exception: 

,MF = L 

specifies the list form of the GETMAIN macro instruction. 



< 
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GETMAIN (Execute Form) 



A remote control program parameter list is used in, and can be modified by, the execute form 
of the GETMAIN macro instruction. The parameter list can be generated by the list form of 
either a GETMAIN or a FREEMAIN. 

The execute form of the GETMAIN macro instruction is written as follows: 



GETMAIN 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede GETMAIN. 

One or more blanks must follow GETMAIN. 



) 



LC 
LU 
VC 

vu 

EC 

EU 

,LA = length addr 
,LV = length value 



,A=addr 

,SP = subpool nmbr 

,BNDRY = DBLWD 
,BNDRY = PAGE 

,RELATED = va/ue 

,MF = (E,ctrl prog) 



length addr: RX-type address or register (2) - (12). 

length value: symbol, decimal digit, or register (2) - (12). 

Note: LA may only be specified with EC or EU above. 

Note: LV may only be specified with LC, LU, VC, or VU above. 

addr: RX-type address, or register (2) - (12). 

subpool nmbr: symbol, decimal digit 0-127, or register (2) - (12). 

Default: BNDRY = DBLWD 

value: any valid macro keyword specified. 

Ctrl prog: RX-type address, or register (1) or (2) - (12). 



) 



The parameters are explained under the standard form of the GETMAIN macro instruction, 
with the following exception: 

,MF = (E,c*r//>rog) 

specifies the execute form of the GETMAIN macro instruction using a remote control 
program parameter list. 
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IDENTIFY - Add an Entry Name 



The IDENTIFY macro instruction is used to add an entry name to a copy of a load module 
currently in virtual storage. The copy must be one of the following: 

• A copy that satisfied the requirements of a LOAD macro instruction issued during the 
execution of the current task. 



• 



The last load module given control, if control was passed to the load module using a 
LINK, ATTACH, or XCTL macro instruction. 



The IDENTIFY macro instruction may not be issued by an asynchronous exit routine. 
Normally, the IDENTIFY macro assigns the identified entry point as reentrant. A user issuing 
this macro should be sure that his program is reenterable, otherwise, results are unpredictable. 

An exception is the case of a non-authorized user identifying a module from an authorized 
library. In this case, the identified entry point is assigned the same attributes (reentrant, serially 
reusable, non-reusable, load only) as the main entry point. If the program is marked 
non-reusable, an ABEND 806 with a return code of four may result. The user should ensure 
that the program issuing this macro is reentrant or serially reusable if this exception applies. 

IDENTIFY services sets the addressing mode of the entry name that was added equal to the 
addressing mode of the major entry name. The system assigns the major entry name according 
to how the load module was constructed. 

• If the load module was constructed using the linkage editor (and brought into virtual 
storage via program fetch or virtual fetch), the major entry name is the name of the load 
module in the partitioned data set directory (not an alias to that member). 

• If the load module was brought into storage by the loader, the major entry name is either 
the name that the user provided as input to the loader or the name that the loader used as 
a default. See the NAME = parameter in the LOADER section of Linkage Editor and 
Loader for information about how to specify this name. 

Note: You can override the addressing mode of the entry name by using the AMODE 
parameter in the PARM field of the EXEC JCL statement. 

If an authorized caller creates an entry name for a module in the pageable link pack area, 
IDENTIFY services places an entry for the alias on the active link pack area queue. If an 
unauthorized caller creates an entry name for a module in the pageable link pack area, 
IDENTIFY services places an entry for the alias on the task's job pack queue. 

The IDENTIFY macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede IDENTIFY. 
IDENTIFY 

b One or more blanks must follow IDENTIFY. 

EP = entry name entry name: symbol 

EPLOC = entry name addr entry name addr: RX-type address, or register (0) or (2) - (12). 

,ENTRY = (?«#7 addr added entry addr added: RX-type address, or register (1) or (2) - (12). 



< 
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Example 1 



) 



The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

specifies the entry name or address of the entry name. The name does not have to 
correspond to any symbol or name in the load module, and must not correspond to any 
name, alias, or added entry name for a load module in the link pack area queue, or the 
job pack area of the job step. If EPLOC is coded, the name must be padded to eight 
bytes, if necessary. 

,ENTRY - entry addr added 

specifies the virtual storage address of the entry point being added. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Successful completion of requested function. 

04 Entry name and address already exist. 

08 Entry name duplicates the name of a load module currently in virtual storage; entry address was not 

added. 

0C Entry address is not within an eligible load module; entry address was not added. 

10 Request issued by an asynchronous exit routine; entry address was not added. 

14 LINK, LOAD, XCTL, ATTACH, or IDENTIFY request was previously issued using the same entry 

name but a different address; current request was ignored. 

18 Parameter list is invalid or is not on a word boundary. 

1C Extent list length is not positive or a multiple of 8, or extent address is not on a double word boundary, 

is not addressable, or is not in caller's region. 

24 Unexpected system error. 

28 EPLOC address is fetch protected. 



Operation: Add an entry name (PGMTAL2A) to a load module in virtual storage. Register 3 
contains the entry point address. 

IDENTIFY EP=PGMTAL2A,ENTRY=(R3) 
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LINK — Pass Control to a Program in Another Load Module 

i 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The LINK macro instruction is used to pass control to a specified entry name in another load 
module; the entry name must be a member name or an alias in a directory of a partitioned data 
set (PDS) or must have been specified in an IDENTIFY macro instruction. The load module 
containing the program is brought into virtual storage if a usable copy is not available. 

LINK processing handles the setting of the addressing mode when passing control. The called 
program is given control in the addressing mode indicated in its PDS directory entry. On entry 
to the called program, the high-order bit, bit 0, of register 14 is set to indicate the addressing 
mode of the issuer of the LINK macro. If bit is 0, the issuer is executing in 24-bit addressing 
mode; if bit is 1, the issuer is executing in 31 -bit addressing mode. This makes it possible to 
return control to the calling program in the addressing mode in which it was executing. 

The problem program optionally can provide a parameter list to be passed to the called 
program. If the called program terminates abnormally, or if the specified entry point cannot be 
located, the task is abnormally terminated. 

The standard form of the LINK macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede LINK. 

LINK | 

b One or more blanks must follow LINK. 

EP = entry name entry name: symbol 

EPLOC = entry name addr entry name addr: A-type address, or register (2) - (12). 

DE = list entry addr list entry addr: A-type address, or register (2) - (12). 

,DCB = deb addr deb addr: A-type address, or register (2) - (12). 

,PARAM = (addr) addr: A-type address, or register (2) - (12). 

,PARAM = (addr),VL = 1 Note: addr is one or more addresses, separated by commas. For example, 

(addr, addr, addr) 

,ID = id nmbr id nmbr: symbol or decimal digit, with a maximum value of 4095. 

,ERRET = err rtn addr err rtn addr: A-type address, or register (2) - (12). 

,LSEARCH = NO Default: No 

,LSEARCH = YES 

The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

specifies the entry name, the address of the entry name, or the address of the name field 

in a 60-byte list entry for the entry name that was constructed using the BLDL macro 

instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. If 

an unauthorized program issues the LINK macro instruction and the DE parameter 

specifies an entry in an authorized library, the program-supplied DE information is 

ignored for integrity reasons. Instead, contents management uses the BLDL macro ■ 

instruction to construct a new list entry containing the DE information for the LINK. ^ 
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Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. The DE information supplied by an 
unauthorized program will also be ignored if the LINK macro instruction is requesting 
access to a program or library that is controlled by the System Authorization Facility. 

,DCB = dcbaddr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. 

If the DCB parameter is omitted or if DCB = is specified when the LINK macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry point name. If the entry point 
name is not found, the link library is searched. 

If the DCB parameter is omitted or if DCB = is specified when the LINK macro 
instruction is issued by a subtask, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry point name. If the entry point name 
is not found, the search is continued as if LINK had been issued by the job step task. 



Note: DCB must reside in 24-bit addressable storage. 



w 



,FARAM = (addr) 

,PARAM = (addr),YL - 1 

specifies address(es) to be passed to the called program. Each address is expanded inline 
to a fullword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. (If this parameter is not 
coded, register 1 is not altered unless the execute form of the LINK macro instruction is 
coded.) 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL = 1 causes the high-order bit of the last address parameter to be set to 
1; the bit can be checked to find the end of the list. 

,ID = id nmbr 

specifies an identifier useful for debugging purposes only. The last fullword of the macro 
expansion is a NOP instruction containing the identifier value in bytes 3 and 4. 

,ERRET = err rtn addr 

specifies the address of a routine to receive control when an error condition that would 
cause an abnormal termination of the task is detected. Register 1 contains the abend 
code that would have resulted had the task abended. The routine does not receive control 
when input parameter errors are detected. 

,LSEARCH = NO 
,LSEARCH = ,YES 

specifies whether (YES) or not (NO) the search is to be limited to the job pack area and 
the first library in the normal search sequence. 



J 
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Example 1 



Operation: Pass control to a specified entry name (PGMLKRUS) in another load module. Let 
the system find the module from available libraries. 



LINK EP=PGMLKRUS 

Example 2 



Operation: Pass control to a specified entry name (PGM A) in another load module, specifying 
(in registers 4, 6, 8) three addresses to be passed to the called program. 

LINK EP=PGMA , PARAM= ( (4), (6), (8)) 



< 
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LINK (List Form) 



) 



) 



Two parameter lists are used in a LINK macro instruction: a control program parameter list 
and problem program parameter list. Only the control program parameter list can be 
constructed in the list form of LINK. Address parameters to be passed in a parameter list to 
the problem program can be provided using the list form of CALL. This parameter list can be 
referred to in the execute form of LINK. 

The list form of the LINK macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede LINK. 
LINK 

b One or more blanks must follow LINK. 

EP = entry name entry name: symbol 

EPLOC = entry name addr entry name addr: A-type address. 

DE = list entry addr list entry addr: A-type address. 

,DCB = deb addr deb addr: A-type address. 

,ERRET = err rtn addr err rtn addr: A-type address. 

,LSEARCH = NO Default: No 
,LSEARCH = YES 

,SF = L 



The parameters are explained under the standard form of the LINK macro instruction, with the 
following exception: 

,SF = L 

specifies the list form of the LINK macro instruction. 

Notes: 

1. Coding the LSEARCH parameter causes a parameter list to be created that is different from 
the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 

2. If ERRET is coded in the list form and not specified in the execute form, the error routine 
specified in the list form will be retained and used in the execute form of the macro 
instruction. If ERRET is specified in both the list and the execute form, the error routine 
specified in the execute form of the macro instruction will be used. 
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LINK (Execute Form) 



Two parameter lists are used in a LINK macro instruction: a control program parameter list 
and an optional problem program parameter list. Either or both of these lists can be remote 
and can be referred to and modified by the execute form of LINK. If only one of the 
parameter lists is remote, parameters that require use of the other parameter list cause that list 
to be constructed inline as part of the macro expansion. 

The execute form of the LINK macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede LINK. 
LINK 

b One or more blanks must follow LINK. 

EP = entry name entry name: symbol. 

EPLOC = entry name addr entry name addr: RX-type address or register (2) - (12). 

DE = list entry addr list entry addr: RX-type address, or register (2) - (12). 

,DCB = deb addr deb addr: RX-type address, or register (2) - (12). 

,PARAM = (addr) addr: RX-type address, or register (2) - (12). 

,PARAM = (addr),VL = 1 Note: addr is one or more addresses, separated by commas. For example, 

(addr, addr, addr) 

,ID = id nmbr id nmbr: symbol or decimal digit, with a maximum value of 4095. 

,ERRET = err rtn addr err rtn addr: RX-type address or register (2) - (12). 

,LSEARCH = NO Default: No 

,LSEARCH = YES 

,MF=(E,/>/y>& addr) prob addr: RX-type address, or register (1) or (2) - (12). 

,SF = (E,ctrl addr) ctrl addr: RX-type address, or register (2) - (12) or (15). 

,MF = (E,prob addr),SF = (E,ctrl addr) 

The parameters are explained under the standard form of the LINK macro instruction, with the 
following exceptions: 

9 MP = (E f probaddr) 

,SF = (E,ctrladdr) 

,MF = (E,prob addr),SF - (E,ctrl addr) 

specifies the execute form of the LINK macro instruction. This form uses a remote 
problem program parameter list, a remote control program parameter list, or both. 

Notes: 

1. Coding the LSEARCH parameter causes a parameter list to be created that is different from 
the list created when LSEARCH is omitted. If you code LSEARCH in either the list or the 
execute form of the macro instruction, you must code it in both forms. 

2. If ERRET is coded in the list form and not specified in the execute form, the error routine 
specified in the list form will be retained and used in the execute form of the macro 
instruction. If ERRET is specified in both the list and the execute form, the error routine 
specified in the execute form of the macro instruction will be used. 



( 
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LOAD — Bring a Load Module into Virtual Storage 

The LOAD macro instruction is used to bring the load module containing the specified entry 
name into virtual storage, if a usable copy is not available in virtual storage. 

LOAD services places the load module in storage above or below the 16 megabyte line 
depending on the module's RMODE, which is specified in the partitioned data set's directory 
entry for the module. 

The responsibility count for the load module is increased by one. On output, the high-order 
byte of register 1 contains the authorization code of the loaded module and the low three bytes 
contain the module's length in doublewords. Control is not passed to the load module; instead, 
the virtual storage address of the designated entry point is returned in register 0. The load 
module remains in virtual storage until the responsibility count is reduced to through task 
terminations or until the effects of all outstanding LOAD requests for the module have been 
canceled (using the DELETE macro instruction), and there is no other requirement for the 
module. 



) 



LOAD services sets the high order bit of the entry point address in register to indicate the 
module's AMODE, which is obtained from the partitioned data set's directory entry for the 
module. If the module's AMODE is 31, it sets the indicator to 1; if the module's AMODE is 
24, it sets the indicator to 0; and if the module's AMODE is ANY, it sets the indicator to 
correspond to the caller's AMODE. 

The entry name in the load module must be a member name or an alias in a directory of a 
partitioned data set or must have been specified in the IDENTIFY macro instruction. If the 
entry name was previously specified in an IDENTIFY macro instruction, no attempt is made to 
bring in an additional copy of the module. If the specified entry name cannot be located, the 
task is abnormally terminated. 



) 



The LOAD macro instruction is written as follows: 



name 
b 

LOAD 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede LOAD. 

One or more blanks must follow LOAD. 



EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 
,DCB = deb addr 

,ERRET = err rtn addr 

,LSEARCH = NO 
,LSEARCH = YES 

,LOAD¥T = addr 

.RELATED = value 



entry name: symbol. 

entry name addr: If LSEARCH or LOADPT is specified, A-type address or 
register (2) - (12); otherwise, RX-type address or register (0) or (2) - (12). 
list entry addr: If LSEARCH or LOADPT is specified, A-type address or 
register (2) - (12); otherwise, RX-type address, or register (2) - (12). 

deb addr: If LSEARCH or LOADPT is specified, A-type address or register 
(2) - (12); otherwise, RX-type address, or register (1) or (2) - (12). 

err rtn addr: RX-type address or register (2) - (12). 

Default: No 

addr: A-type address or register (2) - (12). 
value: any valid macro keyword specification. 
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The parameters are explained as follows: 

EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

specifies the entry name, the address of the name, or the address of the name field in a 
60-byte list entry for the entry name that was constructed using the BLDL macro 
instruction. If EPLOC is coded, the name must be padded to eight bytes, if necessary. 

If an unauthorized program issues the LOAD macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the LOAD. 
The DE information supplied by an unauthorized program will also be ignored if the 
LOAD macro instruction is requesting access to a program or library that is controlled by 
the System Authorization Facility. 

Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

,DCB = deb addr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. 

If the DCB parameter is omitted or if DCB = is specified when the LOAD macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry name. If the entry name is not 
found, the link library is searched. 

If the DCB parameter is omitted or if DCB = is specified when the LOAD macro 
instruction is issued by a subtask, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry name. If the entry name is not found, 
the search is continued as if the LOAD had been issued by the job step task. 

Note: DCB must reside in 24-bit addressable storage. 

,ERRET - err rtn addr 

specifies the address of a routine to receive control when an error condition that would 
cause an abnormal termination of the task is detected. Register 1 contains the abend 
code that would have resulted had the task abended, and register 15 contains the reason 
code that is associated with the abend. The routine does not receive control when input 
parameter errors are detected. 

,LSEARCH = NO 
,LSEARCH = YES 

specifies whether (YES) or not (NO) the search is to be limited to the job pack area and 
the first library in the normal search sequence. 



,LOADPT = addr 
specifies tha 
caller at the indicated address 



DPT = addr 

specifies that the starting address at which the module was loaded is to be returned to the ■ 
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,RELATED = va/«e 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD /DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

LOAD1 LOAD EP=APGIOHKl,RELATED=(DELl, 

' LOAD APGIOHK1 ' ) 



DELI DELETE EP=APGI0HK1 ,RELATED= (LOAD1 , 

' DELETE APGI0HK1 ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

Example 1 

Operation: Bring a load module containing a specified entry name (PGMLKRUS) into virtual 
storage. Let the system find the module from available libraries. 

LOAD EP=PGMLKRUS 

Example 2 

Operation: Bring a load module containing the entry name EPNAME into virtual storage. 
Indicate that register 7 contains the address of the DCB associated with the partitioned data set 
that contains this load module. Return the load address of the requested module in the 
location pointed to by register 8. If an error occurs during this processing, transfer control to 
the error routine located at ERRADDR. 

LOAD EP=EPNAME , DCB= ( 7 ) , LOADPT= ( 8 ) , ERRET=ERRADDR 



\ 
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LOAD (List Form) 



The list form of the LOAD macro instruction builds a non-executable problem program 
parameter list that can be referred to or modified by the execute form of the LOAD macro 
instruction. 

The list form of the LOAD macro instruction is written as follows: 



name 
b 

LOAD 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede LOAD. 

One or more blanks must follow LOAD. 



EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

,DCB = deb addr 

,LSEARCH = NO 
,LSEARCH = YES 

,LOADVT = addr 

,RELATED = va/«e 

,SF = L 



entry name: symbol. 

entry name addr: A-type address. 

list entry addr: A-type address. 

deb addr: A-type address. 

Default: No 

addr: A-type address. 

value: any valid macro keyword specification. 



The parameters are explained under the standard form of the LOAD macro instruction with the 
following exception: 

,SF=L 

specifies the list form of the LOAD macro instruction. 



( 
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LOAD (Execute Form) 



The execute form of the LOAD macro instruction can refer to and modify the parameter list 
constructed by the list form of the macro instruction. 

The execute form of the LOAD macro instruction is written as follows: 



name 
b 

LOAD 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede LOAD. 

One or more blanks must follow LOAD. 



EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

,DCB = deb addr 

,ERRET = err rtn addr 

,LSEARCH = NO 
,LSEARCH = YES 

,LOADPT = addr 

.RELATED = value 

,SF = (E,listaddr) 



entry name: symbol. 

entry name addr: RX-type address, or register (2) - (12). 

list entry addr: RX-type address, or register (2) - (12). 

deb addr: RX-type address, or register (2) - (12). 

err rtn addr: RX-type address, or register (2) - (12). 

Default: No 

addr: RX-type address or register (2) - (12). 

value: any valid macro keyword specification. 

list addr: RX-type address or register (2) - (12) or (15). 



) 



The parameters are explained under the standard form of the LOAD macro instruction with the 
following exception: 

,SF-(E,/wf addr) 

specifies the execute form of the LOAD macro instruction. 
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PGLOAD — Load Virtual Storage Areas into Real Storage 

The PGLOAD macro instruction is used to load specified virtual storage areas into real storage 
in anticipation of future needs. That is, PGLOAD is essentially a page-ahead function. The 
PGLOAD macro instruction performs this function for virtual addresses below 16 Mb; the 
LOAD option of the PGSER macro instruction performs the same function for virtual 
addresses either above or below 16 Mb. Note, however, that a page that has been loaded via 
PGLOAD is eligible for page-out selection in the same manner as a page that has been 
demand-paged into real storage. 

The misuse of this function can have adverse effects on system performance. Causing 
unnecessary pages to be brought into real storage will force more useful pages to be displaced 
and, consequently, cause unnecessary paging activity. Proper use of this function, however, will 
tend to decrease system overhead resulting from page faults. 

The standard form of the PGLOAD macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede PGLOAD. 
PGLOAD 

b One or more blanks must follow PGLOAD. 

R 

,A = start addr start addr: A-type address, or register (1) or (2) - (12). 

,ECB = ecb addr ecb addr: A-type address, or register (0) or (2) - (12). 

,EA = end addr end addr: A-type address, or register (2) - (12) or (15). 

Default: start addr + 1 

,RELEASE = N Default: RELEASE = N 

,RELEASE = Y Note: RELEASE = Y may only be specified with EA above. 

The parameters are explained as follows: 

R 

specifies that no parameter list is being supplied with this request. 

,A = start addr 

specifies the start address of the virtual area to be loaded. 

,ECB = ecb addr 

specifies the address of an ECB that is used to signal event completion. 

,EA = end addr 

specifies the end address + 1 of the virtual area to be loaded. 

,RELEASE = N 
,RELEASE = Y 

specifies that the contents of the virtual area is to remain intact (N) or be released (Y). 



« 
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When control is returned, register 15 contains one of the following return codes: 



Example 1 



> 



Example 2 



Example 3 






Hexadecimal 
Code 

00 
08 



Meaning 

Operation completed normally; ECB posted complete. 

Operation proceeding; ECB will be posted when all page-ins are complete. 



If control is not returned, an ABEND is issued with the following reason codes in register 15: 



Hexadecimal 
Code 

10 



Meaning 

Virtual subarea list entry or ECB address invalid. No ECB is posted. 



If the ECB parameter is coded, the ECB is unchanged if the request was initiated but not 
complete (return code 8), or if an ABEND was issued with return code 10. Otherwise, the ECB 
is posted complete with code 

- Operation completed successfully. 

If the return code issued is 8, the ECB is posted asynchronously when paging I/O has 
completed, with code 

- Operation completed successfully. 



Operation: Page-in a single byte of virtual storage, causing the entire 4096-byte page 
containing that byte to be paged into real storage. 

PGLOAD R / A=(R3) 



Operation: Page-in the virtual storage lying in the range addressed by registers 3 and 4, and 
notify the requestor via posting of the ECB when the page-ins are complete. 

PGLOAD R,A=(R3) ,EA=(R4) ,ECB=(R5) 



Operation: Discard the contents of the virtual pages totally encompassed by START AD and 
ENDAD before new real storage frames are assigned. 

PGLOAD R,A=STANDARD,EA=ENDAD,RELEASE=Y 
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PGLOAD (List Form) 



The list form of the PGLOAD macro instruction uses a virtual subarea list. 
The list form of the PGLOAD macro instruction is written as follows: 



PGLOAD 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede PGLOAD. 

One or more blanks must follow PGLOAD. 



,LA = list addr 

,ECB = ecbaddr 

,RELEASE = N 
.RELEASE = Y 



list addr: A-type address, or register (1) or (2) - (12). 
ecb addr: A-type address, or register (0) - (2) or (15). 
Default: RELEASE = N 



The parameters are explained under the standard form of the PGLOAD macro instruction, with 
the following exceptions: 



specifies that a parameter list is being supplied with this request. 

,LA = list addr 

specifies the address of the first entry of a virtual subarea list. 



< 
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PGOUT — Page Out Virtual Storage Areas from Real Storage 

The PGOUT macro instruction is used to initiate page-out operations for specified virtual 
storage areas that are in real storage. The PGOUT macro instruction performs this function 
for virtual addresses below 16 Mb; the OUT option of the PGSER macro instruction performs 
the same function for virtual addresses either above or below 16 Mb. The PGOUT function is 
complementary to the PGLOAD function. You have the option of specifying that the virtual 
pages to be paged out either remain valid in real storage or be marked invalid and the real 
frames assigned to them be made available for reuse. The use of this option will not prevent 
page faults from occurring on the specified storage. 

The misuse of this function, like the misuse of the PGLOAD function, can have adverse effects 
on system performance. On the other hand, proper use of this function will tend to clean out 
of real storage those pages no longer needed for program execution or not required for some 
period in the future. 

The standard form of the PGOUT macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede PGOUT. 
PGOUT 

b One or more blanks must follow PGOUT. 

R 

,A = start addr start addr: A-type address, or register (1) or (2) - (12). 

,EA = end addr end addr: A-type address, or register (2) - (12) or (15). 

,KEEPREL = N Default: KEEPREL = N 

,KEEPREL = Y 

The parameters are explained as follows: 

R 

specifies that no parameter list is being supplied with this request. 

,A = start addr 

specifies the start address of the virtual area to be paged out. 

,EA = end addr 

specifies the end address + 1 of the virtual area to be paged out. 

,KEEPREL = N 
,KEEPREL = Y 

specifies that the virtual pages will be marked invalid and the real storage frames freed for 
reuse (N) or that the virtual pages will not be invalidated (Y). 



) 
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When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 

Code Meaning 



00 

oc 

10 



Operation completed normally; paging I/O proceeding asynchronously. 

One or more pages specified to be paged out were not paged out. Either the pages were in the nucleus 
in unusable real frames, in SQA or LSQA, in V = R area allocated region, were page fixed, or the system 
resources necessary to perform the page out operations were momentarily unavailable. Paging I/O is 
proceeding normally for all other pages. 

Operation abnormally terminated. Virtual subarea list entry invalid. 



Example 1 



Example 2 



Operation: Page-out the area of real storage totally encompassed by the start and end virtual 
boundaries specified. 

PGOUT R,A=(R3) ,EA=(R4) 



Operation: Create an auxiliary storage copy of a virtual area before continuing to use the area. 
The area will remain in real storage after the page-outs complete. 

PGOUT R , A= ( R3 ) , EA= ( R4 ) , KEEPREL=Y 



< 
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PGOUT (List Form) 



) 



The list form of the PGOUT macro instruction uses a virtual subarea list. 
The list form of the PGOUT macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede PGOUT. 
PGOUT 

b One or more blanks must follow PGOUT. 

L 

,LA = /wf addr list addr: A-type address, or register (1) or (2) - (12). 

,KEEPREL = N Default: KEEPREL = N 

,KEEPREL = Y 

The parameters are explained under the standard form of the PGOUT macro instruction, with 
the following exceptions: 

L 

specifies that a parameter list is being supplied with this request. 

,LA = list addr 

specifies the address of the first entry of a virtual subarea list (VSL). See the topic 
"Virtual Subarea List (VSL)" in Part I for a description of the VSL. 
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PGRLSE — Release Virtual Storage Contents 



The PGRLSE macro instruction is used to release to the system all real storage and auxiliary 
storage associated with specified pageable virtual storage areas. The PGRLSE macro 
instruction performs this function for virtual addresses below 16 Mb; the RELEASE option of 
the PGSER macro instruction performs the same function for virtual addresses either above or 
below 16 Mb. Use PGRLSE when a large area (one or more complete pages) of virtual storage 
within your program no longer has significant contents. 

Functionally, PGRLSE is equivalent to a FREEMAIN macro instruction followed by a 
GETMAIN macro instruction. That is, the virtual space is maintained, but the data is 
discarded. When the page(s) being released is next referred to, that page is cleared to zeros. 
Thus, you can help reduce system overhead by releasing virtual storage when you no longer 
need it. 

Proper use of this function can increase the amount of storage available to the system and 
prevent needless paging I/O activity. Usage of PGRLSE may improve operating efficiency 
when the using program can discard the contents of a large virtual storage area and reuse the 
virtual storage pages; paging operations may be eliminated for those virtual storage pages when 
they are reused. 

The standard form of the PGRLSE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede PGRLSE. 
PGRLSE 

b One or more blanks must follow PGRLSE. 

LA = low addr low addr: A-type address, or register (0) or (2) - (12). 

,HA = high addr high addr: A-type address, or register (1) or (2) - (12). 



The parameters are explained as follows: 

LA = low addr 

specifies the address of the lower boundary of the area to be released. 

,HA = high addr 

specifies the address of the upper boundary + 1 of the area to be released. 

When control is returned, register 1 5 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 Successful completion. 

04 Execution failed. The area specified, or a portion of the area, is protected from the requesting program. 

Any valid portion of the area preceding the protected area is released. 



i 
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Example 1 

Operation: Release the contents of the pages included within the specified areas. Only those 

pages fully encompassed will be nullified. 

PGRLSE LA= ( R4 ) , HA= ( R5 ) 
Example 2 

Operation: Perform the operation in Example 1, but use A-type addresses. 

PGRLSE LA=LOWADDR,HA=HIGHADDR 



) 
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PGRLSE (List Form) 



The list form of the PGRLSE macro instruction is used to construct a control program 
parameter list. 

The list form of the PGRLSE macro instruction is written as follows: 



name 
b 
PGRLSE 



name: symbol. Begin name in column 1. 
One or more blanks must precede PGRLSE. 

One or more blanks must follow PGRLSE. 



LA = low addr, 
HA = high addr, 
MF = L 



low addr: A-type address. 
high addr: A-type address. 



The parameters are explained under the standard form of the PGRLSE macro instruction, with 
the following exception: 

MF = L 

specifies the list form of the PGRLSE macro instruction. 



« 
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PGRLSE (Execute Form) 






A remote control program parameter list is referred to, and can be modified by, the execute 
form of the PGRLSE macro instruction. 

The execute form of the PGRLSE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede PGRLSE. 
PGRLSE 

b One or more blanks must follow PGRLSE. 

LA = /<w addr, low addr: A-type address, or register (0) or (2) - (12). 

HA=%A addr, high addr: A-type address, or register (1) or (2) - (12). 

MF = (E,ctrl addr) Ctrl addr: RX-type address, or register (2) - (12). 

The parameters are explained under the standard form of the PGRLSE macro instruction, with 
the following exception: 

MF = (E,ctrl addr) 

specifies the execute form of the PGRLSE macro instruction using a remote control 
program parameter list. 
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PGSER — Page Services 



The PGSER macro instruction performs the same paging services as PGLOAD, PGOUT, and 
PGRLSE. PGSER performs these services for addresses either above or below 16 Mb. 

The services are: 

• Page load equivalent to PGLOAD 

• Page out equivalent to PGOUT 

• Page release equivalent to PGRLSE 

If the common area is being released and the caller is not in key zero, the caller's key must 
match the key of the storage. 

Regardless of the addressing mode, all addresses passed in registers are used as 31 -bit addresses. 
All RX-type addresses are assumed to be in the addressing mode of the caller. The standard 
form of the PGSER macro instruction is written as follows: 



name 
b 

PGSER 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede PGSER. 

One or more blanks must follow PGSER. 



R 

L 

,LOAD 

,OUT 

,RELEASE 

,LA = list addr 
,A = start addr 

,EA = end addr 

,ECB = ecb addr 



.RELEASE = Y 
.RELEASE = N 

,KEEPREL = Y 
,KEEPREL = N 

.RELATED = value 



list addr: RX-type address or register (1), (2) - (12). 
Note: This parameter is valid only with L. 

start addr: RX-type address or register (1), (2) - (12). 
Note: This parameter is valid only with R. 

Default: EA = start addr 

end addr: RX-type address or register (15), (2) - (12). 

Note: This parameter is valid only with R. 

Default: If LOAD is specified, ECB = 0. 

ecb addr: RX-type address or register (0) or (2) - (12). 

Note: This parameter is optional if LOAD is specified and is invalid for OUT 

and RELEASE. 

Default: RELEASE = N 

Note: This parameter may be specified only if LOAD is specified. 

Default: KEEPREL = N 

Note: This parameter may be specified only if OUT is specified. 

value: any valid macro keyword specification. 



( 
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) 



) 



R 
L 

specifies the manner in which the input is supplied. If R is specified, the user supplies the 
starting and ending addresses of the virtual area for which the service needs to be 
performed. Before processing the request, page services puts these addresses in registers 1 
and 15, respectively. If L is specified, the user supplies the address of the page services 
list (PSL), which specifies the virtual area for which the service is to be performed. Before 
processing the request, page services puts the address of the PSL in register 1. See the 
topic "Page Service List (PSL)" in Part I for a description of the PSL. 

,LOAD 

,OUT 

.RELEASE 

indicates the function to be performed. 

LOAD specifies that a page-in operation is to be initiated for the virtual storage area 
specified, in anticipation of future needs. 

OUT specifies that a page-out operation is to be initiated for the virtual storage area 
specified. 

RELEASE specifies that all real and auxiliary storage, associated with the virtual storage 
area specified, is to be released. 

,LA * list addr 

specifies the address of the page services list (PSL) for L requests. 

tX — start addr 

specifies the address of the start of the virtual area for R requests. 

jEA 38 end addr 

specifies the address of the end of the virtual area for R requests. 

Note: PGLOAD, PGOUT, and PGRLSE use end + 1 as the value for the end address. 

,ECB = ecb addr 

specifies the address of the ECB that is used to signal event completion for a LOAD 
request. 

If an ECB is supplied, the caller must check the return code because the ECB will not be 
posted if the return code is zero. If an ECB is not supplied, it is not necessary to check 
the return code because control returns to the caller only if the request was successfully 
completed; if unsuccessful, page services abnormally terminates the caller. 

Page services verifies that the ECB address is in an area allocated via GETMAIN and 
that the ECB is in the caller's protect key. Before posting the ECB, page services again 
verifies that the ECB is located in an allocated area and that the ECB is in the caller's 
protect key. (This is to check that the allocated area has not been freed via FREEMAIN 
and the protect key has not been changed.) It is the user's responsibility to ensure that 
the page containing the ECB is not freed and that the key is not altered. If either test 
fails, page services does not post the ECB. 
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,RELEASE = Y 
,RELEASE = N 

specifies that all the real and auxiliary storage associated with the virtual storage areas is 
to be released to the system (Y) or that all the real and auxiliary storage associated with 
the virtual storage areas is not to be released to the system (N). 

,KEEPREL = Y 
,KEEPREL = N 

specifies that the virtual pages should be validated again after the page-out completes (Y); 
or that the virtual pages will be marked invalid and the real storage frames freed for reuse 

(N). 

,RELATED = va/we 

provides information to document the macro by relating the service performed to some 
corresponding function or service. The format can be any valid coding value that the user 
chooses. 

On return the register contents are as follows: 

Register Contents 

0-4 The contents are destroyed and unpredictable. 

5-13 The contents are unchanged. 

14 The contents are destroyed and unpredictable. 

15 This register contains the return code. 

The return codes, given in register 15, along with the option used and the meaning follow: 

Option Code Meaning 

LOAD The operation completed normally and the ECB will not be posted. If no ECB is supplied, the 

operation is completed or proceeding. 

LOAD 8 The operation is proceeding. The ECB, if applicable and available, will be posted with X'00' when 

all page-ins are complete. 

OUT The operation completed normally. 

OUT C One or more pages specified to be paged-out was not paged out. The page service is proceeding 

for the other pages 

RELEASE The operation completed normally. 

If an error is found in one of the parameters, the requestor is abnormally terminated with a 
system abend code of X'18A' and one of the following hexadecimal reason codes is provided in 
register 15: 

Hexadecimal 

Code Meaning 

4 A page-release operation abnormally terminated because either a page release was attempted for 

permanently backed storage or a non-system key caller attempted to release storage in a different key. 

10 A page-load operation abnormally terminated because the PSL or ECB address was invalid. (An ECB 

can be specified for a LOAD request.) 

Callers not authorized to use a specific service are abnormally terminated with a system abend 
codeofX'28A\ 



< 
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Example 1 

Operation: Perform the page-load function for the 4096-byte virtual area starting at BUFFER. 
No ECB is supplied. 

PGSER R , LOAD , A=BUFFER , EA=BUFFER+4095 , ECB=0 
Example 2 

Operation: Release the virtual area specified in the PSL located at LOADWORD. 

PGSER L , RELEASE , LA=LOADWORD 
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POST — Signal Event Completion 



Use the POST macro instruction to have the specified ECB (event control block) set to indicate 
the occurrence of an event. If this event satisfies the requirements of an outstanding WAIT or 
EVENTS macro instruction, the waiting task is taken out of the wait state and dispatched 
according to its priority. The bits in the ECB are set as follows: 

Bit of the specified ECB is set to (wait bit) by POST processing. 

Bit 1 is set to 1 (complete bit) by POST processing. 

Bits 2 through 31 are set to the specified completion code by POST processing. 

The POST macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede POST. 
POST 

b One or more blanks must follow POST. 

ecb addr ecb addr: RX-type address, or register (1) or (2) - (12). 

,comp code comp code: symbol, decimal digit, or register (0) or (2) - (12). 



Range of values: to 2-* u -l 



,30 

Default: 
, RELATED = value value: Any valid macro keyword specification. 



The explanation of the parameters is as follows: 

ecb addr 

specifies the address of the fullword event control block representing the event. 

,comp code 

specifies the completion code to be placed in the event control block upon completion. 

,RELATED = va/we 

specifies information used to self-document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 



< 
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Example 1 



Example 2 



) 



The RELATED parameter may be used, for example, as follows: 

WAIT1 WAIT 1,ECB=ECB,RELATED=( RESUME 1, 
' WAIT FOR EVENT ■ ) 



RESUME 1 POST ECB,0 ,RELATED= (WAIT1, 
'RESUME WAITER') 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 



Operation: Signal event completion with a default completion code. POSTECB is the address 
ofanECB. 

POST POSTECB 



Operation: Signal event completion with a completion code of X'7FF\ POSTECB is the 
address of an ECB. 

POST POSTECB ,X'7FF' 
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RACHECK - Check RACF Authorization 

The RACHECK macro instruction is used to provide authorization checking when a user 
requests access to a RACF-protected resource. 

Systems using RACF Version 1, Release 6 or later, have the option to temporarily grant access 
requests to users who do not have sufficient authority instead of unconditionally denying 
requests. In this case, RACF issues a warning message instead of failing the request. RACF 
provides this option on an individual basis; installations can use the warning facility selectively 
via the WARNING = YES keyword of the RACDEF macro for that particular profile, without 
affecting the access control provided by other RACF profiles. 

RACHECK bypasses the warning processing if the OWNER keyword is specified, as this 
indicates that the request is coming from a RACF command processor. 



Notes: 



Do not use the DSTYPE=M or OWNER parameters unless RACF Version 1, Release 4 or 
later is installed on your system. 

Do not use the ACCLVL or RAC FIND parameters unless RACF Version 1, Release 5 or 
later is installed on your system. 

Only callers in 24-bit addressing mode can issue this macro. Callers executing in 31-bit 
addressing mode, who want to use the RACHECK function, can code the RACROUTE 
macro. 
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The standard form of the RACHECK macro instruction is written as follows: 



) 



RACHECK 
b 



name: symbol. Begin name in column 1. 

One or more blanks must precede RACHECK. 

One or more blanks must follow RACHECK. 



) 



ENTITY = {resource name addr) 
,VOLSER = vol addr 



,CLASS= 'classname' 
.CLASS = class name addr 



,RELEASE = number 

,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE = T 

,INSTLN =parm list addr 

,OLDVOL = old vol addr 

,APPL= 'applname' 
,APPL = applname addr 

,OWNER = owner ID addr 

,ACCLVL = (access value addr) 
,ACCLVL = (access value addr, 
parm list addr) 

,RACFIND = YES 
,RACFIND = NO 

.GENERIC = YES 
,GENERIC = ASIS 

,FILESEQ = n?g 
,FILESEQ = number 

„,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 

,STATUS = NONE 
,STATUS = ERASE 



resource name addr: A- type address, or register (2) - (12). 

vol addr: A-type address, or register (2) - (12). 

Note: VOLSER is required only for CLASS = 'DATASET' and DSTYPE 

not equal to M when a discrete profile name is used and only when 

ENTITY is also coded. 

'classname': 1-8 character name. 

class name addr: A-type address, or register (2) - (12). 

Default: CLASS = 'DATASET' 

number: 1.6 or 1.7 
Default: RELEASE =1.6 

reg: register (2) - (12). 
Default: ATTR = READ 



Default: DSTYPE = N 



parm list addr: A-type address, or register (2) - (12). 

old vol addr: A-type address, or register (2) - (12). 
applname addr: A-type address, or register (2) - (12). 

owner ID addr: A-type address, or register (2) - (12). 
access value addr: A-type address or register (2)-(12). 
parm list addr: A-type address or register (2)-(12). 



Default: GENERIC = ASIS 



reg: register (2) - (12). 
number: 1-9999 

Default: TAPELBL = STD 



Default: STATUS = NONE 
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The parameters are explained as follows: 

ENTITY = (resource name addr) " 

ENTITY = (resource name addr) specifies that RACF authorization checking is to be 
performed for the resource whose name is pointed to by the specified address. The 
resource name is a 44-byte DASD data set name for CLASS = 'DATASET' or a 6-byte 
volume serial number for CLASS = 'DASDVOL' or CLASS = 'TAPEVOL'. The length of 
all other resource names is determined from the class descriptor tables. The name must 
be left justified in the field and padded with blanks. 

By establishing and maintaining a resource profile, the resource manager can reduce the 
I/O required to perform RACF authorization checks on highly-accessed resources. 

,VOLSER = vol addr 

specifies the volume serial number, as follows: 

• For non-VSAM DASD data sets and tape data sets, this is the volume serial number 
of the volume on which the data set resides. 

• For VSAM DASD data sets and tape data sets, this is the volume serial number of 
the catalog controlling the data set. 

The field pointed to by the specified address contains the volume serial number padded to 

the right with blanks, if necessary, to make six characters. VOLSER = is only valid and 

must be supplied with CLASS = 'DATASET', (unless DSTYPE = M is specified) and if 4 

ENTITY is also coded. * 

,CLASS= 'classname' 

,CLASS = classname addr 

specifies that RACF authorization checking is to be performed for a resource of the 
specified class. If an address is specified, the address must point to a one-byte field 
indicating the length of the classname, followed by the class name (for example 
DATASET, DASDVOL or TAPEVOL). 

,RELEASE = number 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. For instance, to use the 
RACHECK release 1.7 parameter FILESEQ you must be using RACF 1.7 on your 
system and specify RELEASE = 1.7. If you specify a parameter with an incompatible 
release level, the parameter will not be accepted by the macro processing. An error 
message will be issued at assembly time. For the parameters that are valid for 
RELEASE = 1.6 and later, see Figure 60 on page 254. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 

Execution-time validation of the compatibility between the list and execute forms of the 

RACHECK macro can be done by your specifying the CHECK subparameter on the 

execute form of the macro. a 
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I 



,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 

specifies the access authority of the user or group permitted access to the resource for 

which RACF authorization checking is to be performed: 

READ - RACF user or group can open the resource only to read. 

UPDATE - RACF user or group can open the resource to write or read. 

CONTROL - For VSAM data sets, RACF user or group has authority equivalent to 
the VSAM control password. For non-VSAM data sets and other resources, RACF 
user or group has UPDATE authority. 

ALTER - RACF user or group has total control over the resource. 

If a register is specified, the register must contain one of the following codes in the 
low-order byte of the register: 

X'02' - READ 
X'04' - UPDATE 
X'08' - CONTROL 
X'80' - ALTER 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE = T 

specifies the type of data set associated with the request: 

• N for non-VSAM 

• V for VSAM 

• M for model profile 

• T for tape 

If DSTYPE = T is specified and tape data set protection is not active, the processing will 
be the same as for RACHECK CLASS = 'TAPEVOL\ DSTYPE should only be specified 
for CLASS = 'DATASET\ 

Note: Do not specify DSTYPE = M unless RACF Version 1 , Release 4 or later is 
installed on your system. 

,INSTLN =parm list addr 

specifies the address of an area that is to contain parameter information meaningful to the 
RACHECK installation exit routine. This information is passed to the installation exit 
routine when it is given control from the RACHECK routine. 

The INSTLN parameter can be used by an application program acting as a resource 
manager that needs to pass information to the RACHECK installation exit routine. 
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,OLDVOL = old vol addr 

specifies a volume serial: 

• For CLASS — 'DATASET', within the same multivolume data set specified by 
VOLSER = . 

• For CLASS = 'TAPEVOL', within the same tape volume specified by ENTITY = . 

RACF authorization checking will verify that the OLD VOL specified is part of the same 
multivolume data set or tape volume set. 

The specified address points to the field that contains the volume serial number padded to 
the right with blanks, if necessary, to make six characters. 

,APPL= 'applname' 

, APPL = applname addr 

specifies the name of the application requesting authorization checking. The applname is 
not used for the authorization checking process but is made available to the installation 
exit routine(s) called by the RACHECK routine. If the address is specified, the address 
must point to an 8-byte field containing the application name left justified and padded 
with blanks. 

,OWNER = owner ID addr 

specifies a profile owner id that is compared with the profile owner id in the owner field 
of the RACF profile. If the owner names match, the access authority allowed for that 
userid is 'ALTER'. The address must point to an 8-byte field containing the owner name, 
left-justified and padded with blanks. 

If OWNER is specified, any WARNING and OPERATIONS attribute processing is 
bypassed. 

Note: Do not specify OWNER unless RACF Version 1, Release 4 or later is installed on 
your system. 

,ACCLVL = (access value addr) 

,ACCLVL = (access value addr.parm list addr) 

specifies the tape label access level information for the MVS tape label functions. The 
access value pointed to by the specified address is a one byte length field, containing the 
value (0-8) of the length of the following data, followed by an eight-character string that 
will be passed to the RACHECK installation exit routines. The optional parameter list 
pointed to by the specified address contains additional information to be passed to the 
RACHECK installation exit routines. RACF does not inspect or modify this 
information. 

Note: Do not use the ACCLVL parameter unless RACF Version 1, Release 5 or later is 
installed on your system. 
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,RACFIND = YES 
,RACFIND = NO 

indicates whether or not the resource is protected by a discrete profile. The RACF 
processing and the possible return codes are given in Figure 59. Note that in all cases, a 
return code of X'OC is also possible. 

Note: Do not use the RACFIND parameter unless RACF Version 1, Release 5 or later 
is installed on your system. 



Operand 



Generic Profile Checking 
Inactive 



Generic Profile Checking 
Active 



RACFIND = YES 



Look for discrete profile; 
if found, exit with 
return code 00 or 08. 
If no discrete profile is 
found, exit with return 
code 08. 



Look for discrete profile; 

if found, exit with 

return code 00 or 08. 

Look for generic profile; 

if found, exit with return code 00 

or 08. 

Exit with return code 08 if neither 

a discrete nor a generic profile 

is found. 



RACFIND = NO 



No checking. Exit 
with return code 04. 



Look for generic profile; 
if found, exit with 
return code 00 or 08. 
if not found, exit with 
return code 04. 



\ 



RACFIND not 

specified 



Look for discrete profile; 
if found, exit with 
return code 00 or 08. 
If no discrete profile is 
found, exit with return 
code 04. 



Look for discrete profile; 

if found, exit with 

return code 00 or 08. 

Look for generic profile; 

if found, exit with return code 00 

or 08. 

Exit with return code 04 if neither a 

discrete nor a generic profile is found. 



Figure 59. Types of Profile Checking Performed by RACHECK 

,GENERIC = YES 
,GENERIC = ASIS 

specifies whether the resource name is to be treated as a generic profile name. If 
GENERIC is specified with CLASS = DEFINE, NEWNAME, then GENERIC applies to 
both the old and new names. GENERIC is ignored if the GENCMD option on the 
RACF SETROPTS command is not specified for the class (see RACF Command 
Language Reference). 

This keyword is designed primarily for use by RACF commands. 

• If GENERIC = YES is specified, the resource name is considered a generic profile 
name, even if it does not contain either of the generic characters: an asterisk (*) or a 
percent sign (%). 

• If GENERIC = ASIS is specified, the resource name is considered a generic only if it 
contains either of the generic characters: an asterisk (*) or a percent sign (%). 



J 
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,FILESEQ = number 
,FILESEQ = reg 

specifies the file sequence number of a tape data set on a tape volume or within a tape 
volume set. The value must be in the range 1 - 9999. If a register is specified, it must 
contain the file sequence number in the low-order half-word. If CLASS = 'DATASET' 
and DSTYPE = T are not specified, FILESEQ is ignored. 

,TAPELBL = STD 
,TAPELBL = BLP 
/TAPELBL = NL 

specifies the type of tape label processing to be done: 

• STD - IBM or ANSI standard labels. 

• BLP - bypass label processing. 

• NL - non-labeled tapes. 

For TAPELBL = BLP, the user must have the requested authority to the profile ICHBLP 
in the general resource class FACILITY. For TAPELBL = NL or BLP, the user will not 
be allowed to protect volumes with volume serial numbers in the format "Lnnnnn." 

This parameter is primarily intended for use by data management routines to indicate the 
label type from the LABEL keyword on the JCL statement. 

This parameter is valid only for CLASS = 'DATASET' and DSTYPE = T, or 
CLASS = TAPEVOL'. The default is TAPELBL = STD. 

,STATUS = NONE 
,STATUS = ERASE 

Specifies whether or not RACHECK is to return the erase status of the given data set. 
This parameter is valid only for CLASS = 'DATASET' and a DSTYPE value other than 
T. The default is STATUS = NONE. 

Parameters For RELEASE = 1.6 and Later 

The RELEASE values for which a specific parameter is valid are marked with an 'X'. 



Parameter 


RELEASE = 
1.6 


RELEASE = 

1.7 


ACCLVL= 


X 


X 


APPL = 


X 


X 


ATTR = 


X 


X 


CLASS = 


X 


X 


DSTYPE = N, V, or 
M 


X 


X 


DSTYPE = T 




X 


ENTITY = 


X 


X 


FILESEQ = 




X 


GENERIC = 


X 


X 


INSTLN = 


X 


X 


OLD VOL = 


X 


X 


OWNER = 


X 


X 



Figure 60 (Part 1 of 2). RACHECK Parameters for RELEASE =1.6 and Later 



< 
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Parameter 


RELEASE = 
1.6 


RELEASE = 

1.7 


RACFIND = 


X 


X 


RELEASE = 


X 


X 


STATUS = 




X 


TAPELBL= 




X 


VOLSER = 


X 


X 



Figure 60 (Part 2 of 2). RACHECK Parameters for RELEASE = 1.6 and Later 



Return Codes and Reason Codes 



When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 



Meaning 



00 



> 



04 



The user is authorized by RACF to obtain use of a 
RACF-protected resource. Register 
contains one of the following reason codes: 

00 indicates a normal completion. 

04 indicates STATUS = ERASE was specified and the 
data set is to be erased when scratched. Or the 
warning status of the resource was requested by the RACHECK 
issuer setting bit '10' at offset 12 decimal 
in the RACHECK parameter list and the resource is 
in warning mode. 

The specified resource is not protected by RACF. 
Register contains the following 
reason code: 



00 



indicates a normal completion. 



08 



0C 



64 



) 



The user is not authorized by RACF to obtain use 
of the specified RACF-protected resource. 
Register contains the following 
reason code: 

00 indicates a normal completion. 

04 indicates STATUS = ERASE was specified and the 
data set is to be erased when scratched. 

08 indicates DSTYPE = T or CLASS - 'TAPEVOL' 
was. specified and the user is not authorized 
to use the specified volume. 

0C indicates the user is not authorized to 
use the data set. 

10 indicates DSTYPE = T or CLASS = 'TAPEVOL' 
was specified and the user is not authorized 
to specify LABEL = (,BLP). 

The OLD VOL specified was not part of the multivolume 
data set defined by VOLSER, or it was not part of the 
same tape volume defined by ENTITY. 

Indicates that the CHECK subparameter of the RELEASE 
keyword was specified on the execute form of the RACHECK macro; 
however, the list form of the macro does not have the proper 
RELEASE parameter. Macro processing terminates. 
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Example 1 



Example 2 



Example 3 



Operation: Perform RACF authorization checking using the standard form, for a non-VSAM 
data set controlled by the catalog pointed to by register 8. Register 7 points to the data set 
name, and the RACF user is requesting the highest level of control over the data set. The 
"RACF-indicated" bit in the data set's DSCB is on. 

RACHECK ENTITY=( (R7) ) / VOLSER=(R8) ,CLASS= 'DATASET' , 
ATTR=ALTER , RACFIND=YES 



Operation: Perform RACF authorization checking using the standard form, for a VSAM data 
set pointed to by register 8. Register 7 points to the data set name, and the RACF user is 
requesting the data set for read only. Register 4 points to an area containing additional 
parameter information. 

RACHECK ENTITY=( (R7) ) ,VOLSER=(R8) ,CLASS= • DATASET' , 
DSTYPE=V , INSTLN= ( R4 ) 



Operation: Using the standard form, perform RACF authorization checking for a tape volume 
for read access only. The tape volume is pointed to by register 8 and the volume's access level 
is in register 5. 

RACHECK ENTITY= ( ( R8 ) ) , CLASS= ' TAPEVOL ' , ATTR=READ , 
ACCLVL=( (R5) ) 



< 
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RACHECK (List Form) 



The list form of the RACHECK macro instruction is written as follows: 



RACHECK 
b 



name: symbol. Begin name in column 1. 

One or more blanks must precede RACHECK. 

One or more blanks must follow RACHECK. 



) 



ENTITY = (resource name addr) 
,VOLSER = vol addr 



,CLASS= 'classname' 
,CLASS = class name addr 

,RELEASE = number 

,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE=T 

,INSTLN=/wm list addr 

,OLDVOL = old vol addr 

,APPL= 'applname' 
,APPL = applname addr 

,OWNER = 0w/kt ID addr 

,ACCLVL — (access value addr) 
,ACCLVL = (access value addr, 
parm list addr) 

,RACFIND = YES 
,RACFIND = NO 

,GENERIC = YES 
,GENERIC = ASIS 

,FILESEQ = reg 
,FILESEQ = number 

,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 

.STATUS = NONE 
,STATUS = ERASE 

,MF = L 



resource name addr: A-type address. 

vol addr: A-type address. 

Note: VOLSER is required on either the list or the execute form of the 

macro, but only for CLASS = 'DATASET' and DSTYPE not equal to M 

when a discrete profile name is used. If required, VOLSER must be 

specified on either the list or the execute form of the macro. 

'classname': 1-8 character name. 

class name addr: A-type address, or register (2) - (12). 

Default: CLASS = 'DATASET' 

number: 1.6 or 1.7 
Default: RELEASE =1.6 

reg: register (2) - (12). 
Default: ATTR = READ 



Default: DSTYPE = N 

parm list addr: A-type address. 

old vol addr: A-type address. 
applname addr: A-type address. 

owner ID addr: A-type address. 

access value addr: A-type address or register (2)-(12). 

parm list addr: A-type address or register (2)-(12). 

Default: GENERIC = ASIS 



reg: register (2) - (12). 
number: 1-9999 

Default: TAPELBL = STD 



Default: STATUS = NONE 



) 
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The parameters are explained under the standard form of the RACHECK macro instruction 
with the following exception: 

,MF = L 

specifies the list form of the RACHECK macro instruction. 



i 
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RACHECK (Execute Form) 



The execute form of the RACHECK macro instruction is written as follows: 



RACHECK 
b 



name: symbol. Begin name in column 1 . 

One or more blanks must precede RACHECK. 

One or more blanks must follow RACHECK. 



) 



) 



ENTITY = (resource name addr) 
,VOLSER = vol addr 



,CLASS= 'classname' 
,CLASS = class name addr 

,RELEASE = (number, CHECK) 
, RELEASE = number 
,RELEASE = (,CHECK) 

,ATTR = READ 
,ATTR = UPDATE 
,ATTR = CONTROL 
,ATTR = ALTER 
,ATTR = reg 

,DSTYPE = N 
,DSTYPE = V 
,DSTYPE = M 
,DSTYPE=T 

,INSTLN =parm list addr 

,OLDVOL = old vol addr 

,APPL = 'applname' 
,APPL = applname addr 

,OWNER = owner ID addr 

,ACCLVL = (access value addr) 
,ACCLVL = (access value addr, 
parm list addr) 

,RACFIND = YES 
,RACFIND = NO 

,GENERIC = YES 
,GENERIC = ASIS 

,FILESEQ = reg 
,FILESEQ = number 

,TAPELBL = STD 
,TAPELBL = BLP 
,TAPELBL = NL 

,STATUS = NONE 
,STATUS = ERASE 

,MF=(E,rtrla#) 



resource name addr: RX-type address, or register (2) - (12). 

vol addr: RX-type address, or register (2) - (12). 

Note: VOLSER is required on either the list or the execute form of the 

macro, but only for CLASS = 'DATASET' and DSTYPE not equal to M 

when a discrete profile name is used. If required, VOLSER must be 

specified on either the list or the execute form of the macro. 

'classname': 1-8 character name. 

class name addr: RX-type address, or register (2) - (12). 

Default: CLASS = 'DATASET' 

number: 1.6 or 1.7 
Default: RELEASE =1.6 



reg: register (2) - (12). 
Default: ATTR=READ 



Default: DSTYPE = N 



parm list addr: RX-type address, or register (2) - (12). 

old vol addr: RX-type address, or register (2) - (12). 
applname addr: RX-type address, or register (2) - (12). 

owner ID addr: RX-type address, or register (2) - (12). 

access value addr: RX-type address or register (2)-(12). 
RX-type address or register (2)-(12). 
parm list addr: 



Default: GENERIC = ASIS 



reg: register (2) - (12). 
number: 1-9999 

Default: T APELBL = STD 



Default: STATUS = NONE 

Ctrl addr: RX-type address, or register (1) or (2) - (12). 
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The parameters are explained under the standard form of the RACHECK macro instruction 
with the following exceptions: 

I 

,MF = (E,cfr7 addr) 

specifies the execute form of the RACHECK macro instruction. 

,RELEASE = (number,CHECK) 
,RELEASE = number 
,RELEASE = (,CHECK) 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. For instance, to use the 
RACHECK release 1.7 parameter FILESEQ you must be using RACF 1.7 on your 
system and specify RELEASE = 1.7. If you specify a parameter with an incompatible 
release level, the parameter will not be accepted by the macro processing. An error 
message will be issued at assembly time. For the parameters that are valid for 
RELEASE = 1.6 and later, see Figure 60 on page 254. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACHECK macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute , 

form of the macro, the execute form of the macro will not be done. Instead, a return 'I 

code X'64' will be generated. 



< 
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RACROUTE - MVS Router Interface 

The RACROUTE macro instruction is used to invoke the System Authorization Facility (SAF) 
MVS router, which conditionally directs control to the Resource Access Control Facility 
(RACF) when RACF is present. 

You can use RACROUTE to access the functions that are provided by the following RACF 
macros: RACHECK, and FRACHECK. In coding the RACROUTE macro instruction to 
access a particular RACF macro function, you must also use the necessary parameters from 
that macro on the RACROUTE macro instruction. For example, if you code RACROUTE to 
access the RACHECK function, you must code REQUEST = AUTH and any other required 
parameters and any optional ones you need from the RACHECK macro. RACROUTE 
validates that only the parameters applicable to the RACHECK macro have been coded. 

Notes: 

1. For RACF Version 1 Release 6, all parameters and parameter lists must reside below 16 
megabytes. 

2. For RACF Version I Release 7: 

If a caller is executing in 24-bit addressing mode, all parameters and parameter lists are 
assumed to reside below 16 megabytes. If a caller, however, is executing in 31-bit addressing 
mode, and is calling RACF via the RACROUTE macro instruction, RACF will assume that 
all parameters and parameter lists may reside above the 16 megabytes (that is, that all 
parameter addresses are true 31-bit addresses). 

All parameter lists generated by the RACROUTE macro instruction are in a format that 
allows compiled code to be moved above 16 megabytes without recompilation. 

This 31 -bit support is available only when RACF is called via the RACROUTE, 
FRACHECK, or RACSTAT macro instructions. Any caller that uses the RACHECK macro 
instruction may be in 24-bit addressing mode only. RACF does not support this caller in 
31 -bit mode. 



f 
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The standard form of the RACROUTE macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede RACROUTE. 
RACROUTE 

b One or more blanks must follow RACROUTE. 

REQUEST = AUTH 
REQUEST = FASTAUTH 

,REQSTOR = reqstor addr reqstor addr: A-type address or register (2) - (12). 

Default: zero. 

Note: If REQSTOR = is coded and RACF is installed, the RACF router 
table must be updated to match the operand. 

,SUBSYS = 5«fej5 addr subsys addr: A-type address or register (2) - (12). 

Note: If SUBSYS = is coded and RACF is installed, the RACF router table 
must be updated to match the operand. 

,WORKA = work area addr work area addr: A-type address or register (2) - (12). 

.RELATED = value value: Any valid macro keyword specified. 

,LOC = BELOW Default: See parameter description. 

,LOC = ANY Note: LOC can be coded only if 

,LOC = ABOVE REQUEST = VERIFY or REQUEST = LIST is coded. 

In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST = , some of these are required, some 
optional, and some are invalid. 

The parameters are explained as follows: 

REQUEST = AUTH 
REQUEST = FASTAUTH 

specifies a code that determines the RACF parameter list to be issued internally as well as 
the RACF routine to receive control. The permissible codes and their associated RACF 
macros are as follows: 

AUTH -- RACHECK 
FASTAUTH - FRACHECK 

For RACROUTE to work correctly, once you have chosen a REQUEST code you must 
also code (on the RACROUTE macro) the parameters that belong to the associated 
macro instruction. Please see the associated macro for the necessary parameters. 

Notes: 

1. Data areas returned by RACF to the caller will be either above or below the 16-megabyte line, 
depending upon the caller's addressing mode and the data area in question. 

,REQSTOR = rector addr 

specifies the address of an 8-byte character field containing the control point name (this 
address identifies a unique control point within a set of control points that exists in a 
subsystem). If this operand is coded and RACF is installed, the RACF router table must 
be changed to match the operand. If the table is not updated, the default to bypass 
RACF processing is taken. For a description of the RACF router table and the macro 
used to update it, see SPL: Resource Access Control Facility (RACF). 



If this operand is omitted, a string of eight blanks is assumed. 
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,SUBSYS = Mfoys addr 

specifies the address of an 8-byte character field containing the calling subsystem's name, 
version, and release level. If this operand is coded and RACF is installed, the RACF 
router table must be changed to match the operand. If the table is not updated, the 
default to bypass RACF processing is taken. For a description of the RACF router table 
and the macro used to update it, see SPL: Resource Access Control Facility (RACF). 

If this operand is omitted, a string of eight blanks is assumed. 

, WORKA = work area addr 

specifies the address of a 512-byte work area for use by the MVS router and the RACF 
front end routine. 

,RELATED = va/we 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified is at the discretion of the user, and can be any valid coding value. 

Return Codes and Reason Codes 

When control is returned, register 1 5 contains one of the following return codes: 

Hexadecimal Code Meaning 

00 The requested security function has completed successfully. In addition, if the requested 

function was 'AUTH', the authorization request was accepted. 

04 The requested function has not been processed. In addition, if the request was 'AUTH', 

the MVS router could neither accept nor fail the request. The following are possible 
reasons for a request not being processed. 

- The MVS router is not active. 

- The RACF front end routine detected that a null action was requested for the 
specified request type, resource type, and subsystem ID. 

- The request/resource/subsystem combination could not be found in the router table. 

- RACF is not active on the system, and RACFIND = YES was not specified, and 
there is no RACROUTE installation exit routine (or an exit originated a return code 
of 4). 

- RACF is active on the system, but no profile exists for the specified resource. 

08 The requested function was processed by RACF, the MVS router, or the router exit 

(ICHRTX00) and failed. If the requested function was 'AUTH', the authorization 
request has been failed. If RACF is inactive for an 'AUTH' request with 
RACFIND = YES, then the MVS router fails the request. The RACF or router exit 
return code and reason codes are returned in the first two words of the RACROUTE 
input parameter list. 



) 
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Example 1 



Operation: Invoke the MVS router to perform authorization checking using the standard form, 
for a non-VSAM data set pointed to by register 8. Register 7 points to the data set name and 
the RACF user is requesting the highest level of control over the data set. The 
"RACF-indicated" bit in the data set's DSCB is on. 

RACROUTE REQUEST=AUTH , WORKA=RACWK , ENTITY= ( ( R7 ) ) , X 

VOLSER= ( R8 ) , CLASS= ' DATASET ' , ATTR=ALTER , X 

RACFIND=YES 



RACWK DS CL512 
Example 2 



Operation: Invoke the MVS router to perform authorization checking using the standard form, 
for an IMS/VS transaction pointed to by register 5. The user requests only read access. The 
request is issued on behalf of the IMS/VS subsystem. 

RACROUTE REQUEST-FASTAUTH , SUBS YS=SUBIMS , X 

WORKA=RACWK , ENTITY= ( R5 ) , X 

CLASS= ' TIMS ' , WKAREA=FRACWK , X 
ATTR=READ 



IMS 



SUBIMS 


DC 


CL8 ' I 


FRACWK 


DS 


16F 


RACWK 


DS 


CL512 
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RACROUTE (List Form) 



The list form of the RACROUTE macro instruction is written as follows: 



RACROUTE 

b 



name: symbol. Begin name in column 1. 

One or more blanks must precede RACROUTE. 

One or more blanks must follow RACROUTE. 



REQUEST = AUTH 
REQUEST = FASTAUTH 

.REQSTOR = reqstor addr 



$\JWSYS=subsys addr 

,WORKA = work area addr 
.RELATED = value 



reqstor addr: A-type address. 

Default: zero. 

Note: If REQSTOR = is coded and RACF is installed, the RACF router 

table must be updated to match the operand. 

subsys addr: A-type address. 

Note: If SUBSYS = is coded and RACF is installed, the RACF router table 

must be updated to match the operand. 

work area addr: A-type address or register (2) - (12). 

value: Any valid macro keyword specified. 



,MF = L 

In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST = , some of these are required, some 
optional, and some are invalid. 



) 



The parameters are explained under the standard form of the RACROUTE macro instruction 
with the following exception: 



) 



,MF = L 

specifies the list form of the RACROUTE macro instruction. 



RACROUTE (List Form) 265 



RACROUTE (Execute Form) 



The execute form of the RACROUTE macro instruction is written as follows: 



RACROUTE 

b 



name: symbol. Begin name in column 1 . 

One or more blanks must precede RACROUTE. 

One or more blanks must follow RACROUTE. 



REQUEST = AUTH 
REQUEST = FASTAUTH 

,REQSTOR = reqstor addr 



,SUBSYS = subsys addr 

,WORKA = work area addr 
.RELATED = value 



reqstor addr: RX-type address or register (2) - (12). 

Default: zero. 

Note: If REQSTOR = is coded and RACF is installed, the RACF router 

table must be updated to match the operand. 

subsys addr: RX-type address or register (2) - (12). 

Note: If SUBSYS = is coded and RACF is installed, the RACF router table 

must be updated to match the operand. 

work area addr: RX-type address or register (2) - (12). 

value: Any valid macro keyword specified. 



,MF = (E,ctrladdr) 



Ctrl addr: RX-type address or register (1). 



In addition to the parameters described above, all parameters valid on the RACHECK, and FRACHECK macros are 
permitted on the RACROUTE macro. Depending on the parameter REQUEST = , some of these are required, some 
optional, and some are invalid. 



The parameters are explained under the standard form of the RACROUTE macro instruction 
with the following exception: 

,MF = (E, ctrl addr) 

specifies the execute form of the RACROUTE macro where ctrl addr is the address of the 
associated parameter list. 



< 
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RACSTAT - RACF Status Extract Service 

The RACSTAT macro instruction is used to determine if RACF is active and optionally 
determine if RACF protection is in effect for a given resource class. The RACSTAT macro can 
also be used to determine if a resource class name is defined to RACF. 

RACSTAT is a branch entered service that uses standard linkage conventions. 

Note: For RACF release 1.6 and previous releases, only callers in 24-bit addressing mode can 
issue this macro. 

The standard form of the RACSTAT macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 

b One or more blanks must precede RACSTAT. 
RACSTAT 

b One or more blanks must follow RACSTAT. 

CLASS = 'classname', classname: DASDVOL, TAPEVOL, or any class defined in the RACF class 

descriptor table 
CLASS = classname addr, classname addr: A-type address, or register (2) - (12). 

ENTRY = entry addr entry addr: A-type address, or register (2) - (12). 

,RELEASE = number number: 1.6 or 1.7 

Default: RELEASE =1.6 



The parameters are explained as follows: 

CLASS = 'classname ', 

CLASS = classname addr, 

specifies the classname for which RACF authorization checking is performed. The name 
can be explicitly defined on the macro by enclosing the name in quotes. If specified, the 
address must point to an 8-byte field containing the classname, left justified and padded 
with blanks if necessary. If CLASS = is omitted, the status of RACF is returned. 

ENTRY = entry addr 

specifies the address of a 4-byte area that is set to the address of the specified class in the 
class descriptor table. This operand is ignored when the CLASS = operand is omitted. 

,RELEASE = number 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 61 on page 268. 

The default is RELEASE = 1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACSTAT macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 
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Parameters For RELEASE = 1.6 and Later 

The RELEASE values for which a specific parameter is valid are marked with an 'X'. 



Parameter 


RELEASE = 
1.6 


RELEASE = 
1.7 


CLASS = 


X 


X 


ENTRY = 


X 


X 


RELEASE = 


X 


X 



Figure 61. RACSTAT Parameters for RELEASE = 1.6 and Later 



Return Codes 



When control is returned, register 15 contains one of the following return codes: 

Hexadecimal 

Code Meaning 

00 RACF is active and, if CLASS = was specified, the class is active. 

04 RACF is active; the class is inactive. 

08 RACF is active; the class is not defined to RACF. 

0C RACF is inactive and, if CLASS = was specified, the class is active. 

10 RACF is inactive; the class is inactive. 

14 RACF is inactive; the class is not defined to RACF. 

18 RACF CVT does not exist (RACF is not installed) or an insufficient level of RACF is installed. 

64 Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form 

of the RACSTAT macro; however, the list form of the macro does not have the proper RELEASE 
parameter. Macro processing terminates. 



i 



Reason Codes 



FRACHECK examines the auditing options in effect for the resource for which access authority 
is being determined. It sets a reason code that indicates to FRACHECK's caller whether 
logging of the access attempt should be performed: 



Hexadecimal 

Code Meaning 



00 



04 



The access attempt is not within the scope of the audit or the global audit specification. The user is 
either authorized or unauthorized for the resource as indicated by the return code. 

The access attempt is within the scope of the audit or the global audit specification for the resource. 
Logging of the attempt should be performed by issuing, for example, a RACHECK for the resource for 
which authorization is being determined. RACHECK provides the necessary logging function. 



Note: The class descriptor entry for the specified class is returned to the caller (in the 4-byte 
area addressed by the entry addr), for return codes 00, 04, 0C, and 10. 



( 
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Example 1 



Operation: Determine if the DASDVOL class is active and retrieve the address of its class 
descriptor. A fullword, CDADDR, contains the class descriptor address. 

RACSTAT CLASS= ' DASDVOL ' , ENTRY=CDADDR 



) 



j|^P 
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RACSTAT (List Form) 



The list form of the RACSTAT macro instruction is written as follows: 



RACSTAT 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede RACSTAT. 

One or more blanks must follow RACSTAT. 



CLASS = 'classname', 
CLASS = classname addr, 

ENTRY = entry addr, 
, RELEASE = number 



classname: DATASET, DASDVOL, or TAPEVOL. 

classname addr: A- type address. 

entry addr: A-type address. 

number: 1 .6 or 1 .7 
Default: RELEASE = 1.6 



MF = L 



The parameters are explained under the standard form of the RACSTAT macro instruction 
with the following exception: 

MF = L 

specifies the list form of the RACSTAT macro instruction. 



i 
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RACSTAT (Execute Form) 

The execute form of the RACSTAT macro is written as follows: 



> 



) 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede RACSTAT. 
RACSTAT 

b One or more blanks must follow RACSTAT. 

CLASS = 'classname', classname: DATASET, DASDVOL, or TAPEVOL. 

CLASS = classname addr, classname addr: RX-type address or register (2) - (12). 

ENTRY = entry addr, entry addr: RX-type address or register (2) - (12). 

,RELEASE = (number .CHECK) number: 1 .6 or 1 .7 

,RELEASE = number Default: RELEASE = 1 .6 
.RELEASE = (.CHECK) 

MF = (E,ctrl addr) Ctrl addr: RX-type address or register (1) - (12). 



The parameters are explained under the standard form of the RACSTAT macro instruction, 
with the following exception: 

MF = (E,ctrl addr) 

specifies the execute form of the RACSTAT macro instruction, using a remote control 
program parameter list. 

,RELEASE = (number,CimCK) 
,RELEASE = number 
,RELEASE = (,CHECK) 

specifies the RACF release level of the parameter list to be generated by this macro. 

Certain parameters can be specified only with particular releases. If you specify a 
parameter with an incompatible release level, the parameter will not be accepted by the 
macro processing. An error message will be issued at assembly time. For the parameters 
that are valid for RELEASE = 1.6 and later, see Figure 61 on page 268. 

The default is RELEASE =1.6. 

When you specify the RELEASE keyword, checking is done at assembly time. 
Execution-time validation of the compatibility between the list and execute forms of the 
RACSTAT macro can be done by your specifying the CHECK subparameter on the 
execute form of the macro. 

When CHECK processing is requested, if the size of the list-form expansion is not large 
enough to accommodate all parameters defined by the RELEASE keyword on the execute 
form of the macro, the execute form of the macro will not be done. Instead, a return 
code of X'64' will be generated. 
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RETURN - Return Control 

The RETURN macro instruction restores the control to the calling program and signals normal 
termination of the called program. The return of control is always made by executing a branch 
instruction using the address in register 14. Because the RETURN macro uses a BR 14 to pass 
control, it can be used only when the return is to a program that executes in the same 
addressing mode. The RETURN macro instruction can restore a designated range of registers, 
provide a return code in register 15, and flag the save area used by the called program. 

If registers are to be restored, or if an indicator is to be placed into the save area, register 13 
must contain the address of the save area, which must have the standard format. 

The RETURN macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede RETURN. 
RETURN 

b One or more blanks must follow RETURN. 

(regl) regl and reg2: decimal digits, and in the order 14, 15, through 12. 

(regl,reg2) 

J 

,RC = ret code ret code: decimal digit, symbol, or register (15). The maximum value is 4095. 

The parameters are explained as follows: 

(regl) 
(regl,reg2) 

specifies the register or range of registers to be restored from the save area pointed to by 
the address in register 13. If you omit this parameter, the contents of the registers are not 
altered. Do not code this parameter when returning control from a program interruption 
exit routine. 



causes the control program to flag the save area used by the called program. The 
low-order bit of word 4 of the save area is set to 1 after the registers have been loaded; 
this designates that a called program has executed a return to its caller. Do not specify 
this parameter when returning control from an exit routine. 

,RC = ret code 

specifies the return code to be passed to the calling program. If a symbol or decimal digit 
is coded, the return code is placed right-adjusted in register 15 before return is made; if 
register 15 is coded, the return code has been previously loaded into register 15 and the 
contents of register 15 are not altered or restored from the save area. (If you omit this 
parameter, the contents of register 1 5 are determined by the regl and reg2 parameters.) 

Note: If register 15 is coded and a return code greater than 4095 (decimal) is passed, the 
results could be either an invalid return code in the message or invalid RC testing. 
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Example 1 

Operation: Restore registers 14-12, flag the save area, and return with a code of 0. 

RETURN (14,12) ,T,RC=0 
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SAVE — Save Register Contents 



The SAVE macro instruction stores the contents of the specified registers in the save area at the 
address contained in register 13. If you wish, you may specify an entry point identifier. Write 
the SAVE macro instruction only at the entry point of a program because the code resulting 
from the macro expansion requires that register 15 contain the address of the SAVE macro 
prior to its execution. Do not use the SAVE macro instruction in a program interruption exit 
routine. 

The SAVE macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 

b One or more blanks must precede SAVE. 
SAVE 

b One or more blanks must follow SAVE. 

(regl) regl and reg2: decimal digits, and in the order 14, 15, through 12. 

{regl, regl) 

't 

,id name id name: character string of up to 70 characters or as an * 

The parameters are explained as follows: 

(regl) 

(regl,reg2) 

specifies the register or range of registers to be stored in the save area at the address 
contained in register 13. The registers are stored in words 4 through 18 of the save area. 



,T 

specifies that registers 14 and 15 are to be stored in word 4 and 5, respectively, of the save 
area. This parameter permits you to save two noncontiguous sets of registers. 

If you specify both T and reg2, and regl is any of registers 14, 15, 0, 1, or 2, all of 
registers 14 through the reg2 value are saved. 

,id name 

specifies an identifier to be associated with the SAVE macro instruction. If an asterisk (*) 
is coded, the identifier is the name associated with the SAVE macro instruction, or, if the 
name field is blank, the control section name is used. The identifier aids in locating a 
program's save area in a dump. If the CSECT instruction name field is blank, the 
parameter is ignored. 

Whenever a symbol or an asterisk is coded, the following macro expansion occurs: 

• A count byte containing the number of characters in the identifier name is assembled four 
bytes following the address contained in register 15. 

• The character string containing the identifier name is assembled starting at five bytes 
following the address contained in register 15. 

• An instruction to branch around the count and identifier fields is assembled. 



( 
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Example 1 

Operation: Save registers 14-12, and associate the identifier with the CSECT name. 

SAVE (14,12),,* 



> 



) 
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SEGLD — Load Overlay Segment and Continue Processing 

The SEGLD macro instruction causes the control program to load the specified segment and 
any segments in its path that are not part of a path already in virtual storage. Control is not 
passed to the specified segment, but is returned to the instruction following the SEGLD macro 
instruction. Processing is overlapped with the loading of the segment. Refer to the Linkage 
Editor and Loader for details on overlay. 

Note: This macro can be used only by callers in 24-bit addressing mode. 

The SEGLD macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SEGLD. 
SEGLD 

b One or more blanks must follow SEGLD. 

ext seg name ext seg name: symbol. 

The parameters are explained as follows: 

ext seg name 

specifies the name of a control section or an entry name in the required section. An 
exclusive reference is not allowed. The name does not have to be identified by an 
EXTRN statement. 



Example 1 



Operation: Cause the control program to load segment PGM54. 

SEGLD PGM54 



< 
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SEGWT — Load Overlay Segment and Wait 



) 



Example 1 



~m 



The SEGWT macro instruction causes the control program to load the specified segment and 
any segments in its path that are not part of a path already in virtual storage. Control is not 
passed to the specified segment; control is not returned to the segment issuing the SEGWT 
macro instruction until the requested segment is loaded. Refer to the publication Linkage 
Editor and Loader for details on overlay operations. The SEGWT macro instruction cannot be 
used in an asynchronous exit routine. 

Note: This macro can be used only by callers in 24-bit addressing mode. 

The SEGWT macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SEGWT. 
SEGWT 

b One or more blanks must follow SEGWT. 

ext seg name ext seg name: symbol. 



The parameters are explained as follows: 

ext seg name 

specifies the name of a control section or an entry name in the required section. An 
exclusive reference is not allowed. The name does not have to be identified by an 
EXTRN statement. 



Operation: Cause the control program to load segment PGMWT. 
SEGWT PGMWT 
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SETRP — Set Return Parameters 

The SETRP macro instruction is used to indicate the various requests that a recovery exit may 
make. It may be used only if a system diagnostic work area (SDWA) was passed to the 
recovery exit. The macro instruction is valid only for ESTAE/ESTAI exits. (The SDWA 
mapping macro - IHASDWA - must be included in the routine that issues SETRP.) 

The SETRP macro instruction is written as follows: 



name 
b 

SETRP 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SETRP. 

One or more blanks must follow SETRP. 



,WKAREA = (reg) 

,KEGS = (regl) 
,REGS = (regl,reg2) 



reg: decimal digits 1-12. 
Default: WKAREA = (1) 

regl: decimal digits 0-12, 14 15. 
reg2: decimal digits 0-12, 14, 15. 
Note: If regl and reg2 are both specified, order is 14, 15, 0-12. 



,DUMP = IGNORE 
,DUMP = YES 
,DUMP = NO 



Default: DUMP = IGNORE 



.DUMPOPT =parm list addr 



,REASON = «wfe 



parm list addr: RX-type address, or register (2) - (12). 
Note: This parameter may be specified only if DUMP : 
above. 



: YES is specified 



code: any four-byte number specified in decimal (31 -bit) or hexadecimal 
(32-bit). 



,RC = 
,RC = 4 
,RC=16 



Default: RC = 



,RET ADDR = retry addr retry addr: RX-type address, or register (2) - (12). 

Note: This parameter may be specified only if RC = 4 is specified above. 
reg info addr: RX-type address, or register (2) - (12). 

.RETREGS = NO reg info addr: RX-type address, or register (2) - (12). 

,RETREGS = YES Default: RETREGS = NO 

,RETREGS = YES.RUB = reg info addr Note: This parameter may be specified only if RC = 4 is specified above. 

,FRESDWA = NO Default: FRESDWA = NO 

,FRESDWA = YES Note: This parameter may be specified only if RC = 4 is specified above. 

,COMPCOD = comp code comp code: symbol, decimal digit, or register (2) - (12). 

,COMPCOD = {comp code,\JSER) Default: COMPCOD = (comp cocfe,USER) 

,COMPCOD = (comp co<te,SYSTEM) 



The parameters are explained as follows: 

,WKAREA = (reg) 

specifies the address of the SDWA passed to the recovery exit. If this parameter is 
omitted the address of the SDWA must be in register 1. 



< 
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,REGS = (regl) 

,R£GS = (regl,reg2) 

specifies the register or range of registers to be restored from the save area pointed to by 
the address in register 13. If REGS is specified, a branch on register 14 instruction will 
also be generated to return control to the control program. If REGS is not specified, the 
user must code his own return. 

,DUMP = IGNORE 
,DUMP = YES 
,DUMP = NO 

specifies that the dump option fields will not be changed (IGNORE), will be zeroed (NO), 
or will be merged with dump options specified in previous dump requests, if any (YES). 
If IGNORE is specified, a previous exit had requested a dump or a dump had been 
requested via the ABEND macro instruction, and the previous request will remain intact. 
If NO is specified, no dump will be taken. 

,DUMPOPT =parm list addr 

specifies the address of a parameter list that is valid for the SNAP macro instruction. The 
parameter list can be created by using the list form of the SNAP macro instruction, or a 
compatible list can be created. If the specified dump options include subpools for storage 
areas to be dumped, up to seven subpools can be dumped. Subpool areas are 
accumulated and wrapped, so that the eighth subpool area specified replaces the first. 
The TCB, DCB, and STRHDR options available on SNAP will be ignored if they appear 
in the parameter list. The TCB used will be the one for the task that suffered error. The 
DCB used will be one created by the control program and either SYSABEND, 
SYSMDUMP, or SYSUDUMP will be used as a DDNAME. 

,REASON = c0<fe 

specifies the reason code that the user wishes to pass to subsequent recovery exits. 

,RC = 
,RC = 4 
,RC = 16 

specifies the return code the user exit routine sends to recovery processing to indicate 
what further action is required: 

- Continue with termination, causes entry into previously specified recovery routine, if any. 

4 - Retry using the retry address specified. 

16 - Suppress further ESTAI/STAI processing (for ESTAI only). 

,RETADDR = refry addr 

specifies the address of the retry routine to which control is to be given. 

,RETREGS = NO 

,RETREGS = YES 

,RETREGS - YES,RUB = reg info addr 

specifies the contents of the registers on entry to the retry routine. If NO is specified or 
defaulted, only parameter registers (14-2) are passed; all others are unpredictable. If YES 
is specified, the contents of the SDWASRSV field will be used to initialize registers 0-14 
when an FRR requests retry and registers 0-15 when an ESTAE requests a retry. For 
ESTAE exits, this field contains the registers at the last interruption of the RB level at 
which retry will occur. For ESTAI exits, the contents of SDAWSRSV must be set by the 
user either before SETRP is issued or by use of the RUB parameter; any field not set will 
cause the corresponding register to contain on entry to the retry routine. 
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RUB specifies the address of an area (register update block) that contains register update 
information. The data specified in this area will be moved into the SDWA and will be 
loaded into the general purpose registers on entry to the retry routine. The maximum 
length of the RUB is 66 bytes. 

• The first two bytes represent the registers to be updated, register corresponding to 
bit 0, register 1 corresponding to bit 1 , and so on. The user indicates which of the 
registers are to be stored in the SDWA by setting the corresponding bits in these two 
bytes. 

• The remaining 64 bytes contain the update information for the registers, in the order 
0-15. If all 16 registers are being updated, this field consists of 64 bytes. If only one 
register is being updated, this field consists of only 4 bytes for that one register. 

For example, if only registers 4, 6, and 9 are being updated: 

• Bits 4, 6, and 9 of the first two bytes are set. 

• The remaining field consists of 12 bytes for registers 4, 6, and 9; the first 4 bytes are 
for register 4, followed by 4 bytes for register 6, and 4 final bytes for register 9. 

,FRESDWA = NO 
,FRESDWA = YES 

specifies that the entire SDWA be freed (YES) or not be freed (NO) prior to entry into 
the retry routine. 

,COMPCOD = comp code 
,COMPCOD = (comp code,USER) 
,COMPCOD = (comp code,SYSTEM) 

specifies the user or system completion code that the user wishes to pass to subsequent 

recovery exits. 



Example 1 



Operation: Request continue with termination, suppress dumping, restore register 14 from the 
save area and pass control to the location it contains, contain the SDWA in the location 
addressed by register 3, and change the completion code to 10. 



RC=0 , DUMP=NO , REGS= ( 14 ) , WKAREA= ( 3 ) , 
COMPCOD= ( X ' 00A ' , USER ) 



SETRP RC=0 , DUMP=NO , REGS= ( 14 ) , WKAREA= ( 3 ) , X 

Example 2 



Operation: Retry using address X, take a dump before retry, use the contents of SDWASRSV 
to initialize the registers, free the SDWA before control is passed to the retry address, and 
restore registers 14-12. 

SETRP RC=4,RETREGS=YES,DUMP=YES,FRESDWA=YES, X 

REGS= (14,12), RETADDR=X 



i 



( 
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SNAP — Dump Virtual Storage and Continue 



> 



> 



You can use the SNAP macro instruction to obtain a dump of some or all of the storage 
assigned to the current job step. You can also dump some or all of the control program fields. 
The SNAP macro instruction causes the specified storage to be displayed in the addressing 
mode of the caller. 

You must provide a data control block and issue an OPEN macro instruction for the data set 
before any SNAP macro instructions are issued. The DCB macro instruction must contain the 
following parameters: 

DSORG=PS , RECFM=VBA , MACRF= ( W ) , BLKS IZE=nnn , LRECL=xxx , 
and DDNAME=any name but SYSABEND, SYSMDUMP or SYSUDUMP 

The DCB and TCB must reside in 24-bit addressable storage. All other parameters can reside 
above 16 Mb if the issuer is executing in 31 -bit addressing mode. 

If a standard dump of 120 characters per line is requested, BLKSIZE must be either 882 or 
1632, and LRECL must be 125. (The data control block and the DCB macro instruction are 
described in Data Management Services Guide and Data Management Macro Instructions.) A 
high-density dump printed on a 3800 Printing Subsystem has 204 characters per line. To obtain 
a high-density dump, you must code CHARS = DUMP on the DD statement describing the 
dump data set. The BLKSIZE = must be either 1470 or 2724, and the LRECL = must be 209. 
You can also code CHARS = DUMP on the DD statement describing a dump data set that will 
not be printed immediately. If you specify CHARS = DUMP and the output device is not a 
3800, print lines are truncated and print data is lost. If you open a SNAP data set in a problem 
program that will be processed by the system loader, your problem program must close the data 
set. 

There are three ways to obtain a dump: 

1 . Spool the dump by specifying SYSOUT = x on the DD statement. The dump is printed 
without a separate job but is deferred until after the job ends. 

2. Select a tape or direct access device. This method requires a separate job step to print the 
dump. This method might be used if the dump is to be printed more than once. 

3. Select a printer on the DD statement. This method is almost never used because the printer 
cannot be used by anyone else for the duration of the job step. 

Both NUC and ALLVNUC are valid. Only ALLVNUC gives you the whole virtual nucleus. 



SNAP — Dump Virtual Storage and Continue 28 1 



The standard form of the SNAP macro instruction is written as follows: 



name 
b 
SNAP 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede SNAP. 

One or more blanks must follow SNAP. 



DCB = deb addr 

,TCB = tcbaddr 
,ID = id nmbr 

,SDATA = AIX 
,SDATA = (sys data code) 



deb addr: A-type address, or register (2) - (12). 

tcb addr: A-type address, or register (2) - (12). 

id nmbr: symbol, decimal digit, or register (2) - (12). 
Value range: 0-255 

sys data code: any combination of the following, separated by commas. If you 
specify only one code, you do not need the parentheses. 



,PDATA = ALL 
,PDATA = (prob data code) 



NUC CB ERR 

SQA Q IO 

LSQA TRT ALLVNUC 

PCDATA 

SWA DM SUM 



prob data code: any combination of the following, separated by commas. If 
you specify only one code, you do not need the parentheses. 



,STORAGE = (?M addr, end addr) 
,LIST = list addr 



,STRHDR= (hdr addr) 
,STRHDR = M<r list addr 



,SUBPLST = sbp list addr 



PSW 

REGS 

SA or SAH 

JPA or LPA or ALLPA 

SPLS 

SUBTASKS 

strt addr: A-type address, or register (2) - (12). 

end addr: A-type address, or register (2) - (12). 

list addr: A-type address, or register (2) - (12). 

Note: One or more pairs of addresses may be specified, separated by commas. 

For example: 

STORAGE = (strt addr, end addr, strt addr, end addr) 

hdr addr: A-type address, or register (2) - (12). 

Note: hdr addr is one or more addresses separated by commas. If you specify 

only one header address as an A-type address, you do not need the 

parentheses. If you specify one or more registers, then you must code double 

parentheses (one set enclosing each register and one set enclosing the list of 

registers). If STRHDR = (hdr addr) is specified, then STORAGE must also be 

specified. 

hdr list addr: A-type address, or register (2) - (12). 

Note: If STRHDR = hdr list addr is specified, then LIST must also be 

specified. 

sbp list addr: A-type address, or register (2) - (12). 



The parameters are explained as follows: 



DCB = deb addr 

specifies the address of a previously opened data control block for the data set that is to 
contain the dump. 

Note: DCB must reside in 24-bit addressable storage. 



( 
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,TCB = tcbaddr 

specifies the address of a fullword on a fullword boundary containing the address of the 
task control block for a task of the current job step. If omitted, or if the fullword 
contains 0, the dump is for the active task. If a register is designated, the register can 
contain to indicate the active task, or can contain the address of a TCB. 

Note: TCB must reside in 24-bit addressable storage. 

,ID = id nmbr 

specifies the number that is to be printed in the identification heading with the dump. If 
the number specified is not in the acceptable value range, it will not be printed properly in 
the heading. 

,SDATA = ALL 
,SDATA = (sys data code) 

specifies the system control program information to be dumped: 

ALL All of the SDATA options except ALLVNUC (The read-only portion of the nucleus is not 

included in the dump unless ALLVNUC is also specified as an option.) 

NUC The PSA, SQA, LSQA, and the read/write portion of the nucleus (if the entire nucleus is required, 

specify the ALLVNUC option.) 

Note: The CVT will be included if this option is specified. 

SQA The system queue area (subpools 226, 239, and 245). 

LSQA The local system queue area and subpools 229 and 230. 

SWA The scheduler work area related to the task (subpools 236 and 237). 

CB The control blocks for the task. 

Q The global resource serialization control blocks for the task. 

TRT The GTF trace and system trace data. If system tracing is active and the requestor is authorized, 

all system trace entries for all address spaces are included in the dump. Unauthorized requestors 
obtain those system trace entries, after the job-start time stamp in the ASCB, for their current 
address space. If GTF tracing is active, only the GTF trace entries for the current address space 
are included in the dump. 

DM Data management control blocks for the task. 

ERR Recovery/termination control blocks for the task. These control blocks summarize information 

that describes abnormal terminations of the task. 

IO Input/Output supervisor control blocks for the task. 

ALLVNUC The entire virtual nucleus, the PSA, LSQA, and SQA. (The NUC option will not dump the 
read-only section of the nucleus.) If the SNAP parameter list is used for a SYSMDUMP, the 
ALLVNUC option is converted to ALLNUC on the SVC dump parameter list. 

Note: The CVT is included if this option is specified. 

PCDATA Program call information for the task. 

The SUM option is valid for an abending task or on a list form of the SNAP macro 
instruction pointed to by the DUMPOPT keyword of the ABEND or SETRP macro 
instructions. The option SUM causes the dump to contain a summary dump. If SUM is 
the only option requested, the dump contains a dump header, control blocks, and the 
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other areas listed below. The header information, which is provided for all ABEND 
dumps, consists of the following information: 

• The dump title 

• The ABEND code and program status word (PSW) at the time of the error 

• If the PSW contains the address of an active load module: 

— The name and PSW address of the load module in error 

— The offset, into the load module, at which the error occurred 

The following control blocks and areas are also included in the dump: 

• The control blocks dumped for the CB option 

• The error control blocks (RTM2WAs and SCBs) 

• The save areas 

• The registers at the time of the error 

• The contents of the load module (if the PSW contains the address of an active load 
module) 

• The module pointed to by the last PRB (if it can be found) 

• IK of storage before and after the addresses pointed to by the PSW and the registers 
at the time of the error. 

Note: This storage will only be dumped if the caller is authorized to obtain it. The 
storage is printed by ascending storage addresses with duplicate addresses removed. 

• System trace entries after the job-start time stamp in the ASCB for the current 
address space. 

Note: The GTF trace records are not included. 

If other options are specified with SUM, the summary dump is dispersed throughout the 
dump. See the topic "SNAP Dumps" for an example of how this is done. 

,PDATA = ALL 

,PDATA = (prob data code) 

specifies the problem program information to be dumped: 

ALL All of the following fields. 

PSW Program status word when the SNAP or ABEND macro instruction was issued. 

REGS Contents of the floating-point registers and general-purpose registers when the SNAP or ABEND 

macro instruction was issued. Also, contents of the vector registers, vector status register, and the 
vector mask register when the SNAP or ABEND macro instruction was issued for any task that 
uses the Vector Facility. 

SA Save area linkage information, program call linkage information, and a back trace through save 

areas. 
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SAH Save area linkage information and program call linkage information. 

JPA Contents of job pack area. 

LPA Contents of active link pack area for the requested task. 

ALLPA Contents of job pack area and active link pack area for the requested task. 

SPLS All virtual storage subpools (0-127,252). 

SUBTASKS The designated task and the program data information for all of its subtasks. 

,STORAGE = (s*rf addr,end addr) 

,LIST = list addr 

specifies one or more pairs of starting and ending addresses or a list of starting and 
ending addresses of areas to be dumped. Each starting address is rounded down to a 
fullword boundary; each ending address is rounded up to a fullword boundary. The area 
is then dumped in fullword increments. Callers executing in either 24-bit or 31 -bit 
addressing mode must set the high-order bit of the fullword containing the last address in 
this list to 1. Callers executing in 31 -bit addressing mode must ensure that this bit is 
cleared in all other addresses in the list because SNAP processing truncates the list at the 
first address that contains a 1 in the high order bit. 

,STRHDR = (hdr addr) 

,STRHDR = hdr list addr 

specifies one or more header addresses or the address of a list of header addresses. Each 
header address must be the address of a one byte header length field, which is followed by 
the text of the header. The header has a maximum length of 100 characters. 

If the STORAGE parameter was specified, the STRHDR (storage header) value must be 
one or more header addresses. The number of pairs of starting and ending addresses 
specified for STORAGE must be the same as the number of header addresses specified for 
STRHDR. If a header is not desired for a storage area, a comma must be used to 
indicate its absence. 

If the LIST parameter was specified, the STRHDR value must be the address of a list of 
header addresses. The list of addresses must begin on a fullword boundary, and the high 
order bit of the fullword containing the last address of the list must be set to 1 . The 
number of pairs of starting and ending addresses supplied with the LIST parameter must 
be the same as the number of addresses in the list supplied with STRHDR. If a header is 
not desired for a storage area, the STRHDR list must contain a zero address to indicate 
its absence. 

,SUBPLST = sbp list addr 

specifies the address of a list of subpool numbers to be dumped. Each entry in the list 
must be a two-byte entry and must specify a valid subpool number. The first halfword of 
the list must contain the number of subpools in the list and must be on a fullword 
boundary. If you specify an invalid subpool number or a subpool number for which you 
do not have authorization, the number is skipped and you receive a comment in the dump 
output indicating the error. If a subpool contains 4k blocks of data that are mapped 
from a linear data set, the dump includes only the blocks that have changed since the 
last DIV SAVE function was invoked. 

Note: A maximum of seven subpool numbers is permitted on the list form of the SNAP 
macro instruction pointed to by the DUMPOPT keyword of ABEND or SETRP. 
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Control is returned to the instruction following the SNAP macro instruction. When control is 
returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 

00 

04 

08 



0C 



Meaning 

Successful completion. 

Data control block was not open, or an invalid page exception occurred during the validity check of the 
DCB parameters. 

Task control block address was not valid, an invalid page reference occurred during the validity check of 
the TCB address, a subtask is a job step task, sufficient storage was not available, or the READ for 
JFCB or JFCBE failed. In all cases, the dump is canceled. (Message IEA997I is issued when the 
READ for JFCB or JFCBE fails.) 

Data control block type (DSORG, RECFM, MACRF, BLKSIZE, or LRECL) was incorrect, or the 
DCB's BLKSIZE and/or LRECL were not compatible with the dump format options specified on the 
dump-related DD statement. 



Example 1 



Example 2 



Example 3 



Operation: Dump the storage ranges pointed to by register 9, and dump all PDATA and 
SDATA options. 

SNAP DCB= ( 8 ) , TCB= ( 5 ) , PDATA=ALL , SDATA=ALL , LIST= ( 9 ) 



Operation: Dump the storage ranges pointed to by register 9, and dump only the trace table 
and enqueue control blocks. 

SNAP DCB=(8) ,TCB=(5) , ID=4 ,LIST= (9) , SDATA= ( TRT , Q ) 



Operation: Dump storage area 1000-2000 with no header, and dump storage area 3000-4000 
with a header of 'USER LABEL ONE'. The comma specified in the value for STRHDR 
indicates that no header is wanted for storage area 1000-2000. 

SNAP DCB=(8) ,STORAGE=(1000, 2000, 3000, 4000) , X 
STRHDR=(,L1) 



LI DC ALl(L'HDRl) 

HDR1 DC C'USER LABEL ONE' 



< 
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Operation: Dump storage area 1000-1999 with a header of 'LABEL ONE' and dump storage 
area 3000-3999 with a header of 'LABEL TWO'. 

SNAP DCB= ( 8 ) , LIST=X , STRHDR=L1 



X 


DC 


A(IOOO) 


Start address 




DC 


A(1999) 


End address 




DC 


A(3000) 


Start address 




DC 


X'80' 


End of list indicator 




DC 


AL3(3999) 


End address 


LI 


DC 


A(HDR1) 


Address of length label for 
header one 




DC 


X'80 1 


End of list 




DC 


AL3(HDR2) 


Address of length label for 
header two 


HDR1 


DC 


ALI(L'HDRIA) 


Length of header one 


HDR1A 


DC 


C 1 LABEL ONE' 


Header one 


HDR2 


DC 


AL1(L'HDR2A) 


Length of header two 


HDR2A 


DC 


C 1 LABEL TWO 1 


Header two 



Example 5 



■ 



Operation: Dump subpool 0, 1, and 2 storage related to the current TCB. 

SNAP DCB=XYZ,TCB=0,SUBPLST=SUBADDR 



SUBADDR 



DS OF 


Fullword boundary 


DC X'0003' 


Number of entries in the list 


DC X'0000 1 


Subpool 


DC X'OOOl' 


Subpool 1 


DC X'0002' 


Subpool 2 



) 
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SNAP (List Form) 



Use the list form of the SNAP macro to construct a control program parameter list. You can 
specify any number of storage addresses using the STORAGE parameter. Therefore, the 
number of starting and ending address pairs in the list form of SNAP must be equal to the 
maximum number of addresses specified in any execute form of the macro, or a DS instruction 
must immediately follow the list form to allow for the maximum number of addresses. 

The list form of the SNAP macro instruction is written as follows: 



name 
b 

SNAP 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede SNAP. 

One or more blanks must follow SNAP. 



DCB = deb addr 
,ID = id nmbr 

,SDATA = ALL 
,SDATA = (sys data code) 



deb addr: A-type address. 

id nmbr: symbol or decimal digit. 
Value range: 0-255 

sys data code: any combination of the following, separated by commas. If you 
specify only one code, you do not need parentheses. 



,PDATA = ALL 
,PDATA = iprob data code) 



NUC CB ERR 

SQA Q 10 

LSQA TRT ALLVNUC 

PCDATA 

SWA DM SUM 



prob data code: any combination of the following, separated by commas. If 
you specify only one code, you do not need parentheses. 



,STORAGE = (yM addr, end addr) 
,LIST = list addr 



,STRHDR = (hdr addr) 

,STRHDR = Mr list addr 

,SUBPLST = sbp list addr 
,MF = L 



PSW 

REGS 

SA or SAH 

JPA or LPA or ALLPA 

SPLS 

SUBTASKS 

strt addr: A-type address. 

end addr: A-type address. 

list addr: A-type address. 

Note: One or more pairs of addresses may be specified, separated by commas. 

For example: 

STORAGE = (strt addr, end addr, strt addr, end addr) 

hdr addr: A-type address. 

Note: hdr addr is one or more addresses separated by commas. If you specify 
only one header address, you do not need the parentheses. If STRHDR = (hdr 
addr) is specified, then STORAGE must also be specified. 

hdr list addr: A-type address. 

Note: If STRHDR = hdr list addr is specified, then LIST must also be 

specified. 

sbp list addr: A-type address. 



< 
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The parameters are explained under the standard form of the SNAP macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the SNAP macro instruction. 
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SNAP (Execute Form) 



A remote control program parameter list is referred to and can be modified by the execute form 
of the SNAP macro instruction. 

If you code only the DCB, ID, MF, or TCB parameters in the execute form of the macro 
instruction, the bit settings in the parameter list corresponding to the SDATA, PDATA, LIST, 
and STORAGE parameters are not changed. However, if you code the SDATA, PDATA, or 
LIST parameters, the bit settings for the coded parameter from the previous request are reset to 
zero, and only the areas requested in the current macro instruction are dumped. 

The execute form of the SNAP macro instruction is written as follows: 



name 
b 

SNAP 
b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SNAP. 

One or more blanks must follow SNAP. 



DCB = deb addr 

,TCB = tcbaddr 
,TCB = 'S' 
,ID = id nmbr 

,SDATA = ALL 
,SDATA = (jy5 data code) 



deb addr: RX-type address, or register (2) - (12). 
tcb addr: RX-type address, or register (2) - (12). 

id nmbr: symbol, decimal digit or register (2) - (12). 
Value range: 0-2S5 

sys data code: any combination of the following, separated by commas. If you 
specify only one code, you do not need parentheses. 

NUC CB ERR 

SQA Q IO 

LSQA TRT ALLVNUC 

PCDATA 

SWA DM SUM 



,PDATA = ALL 
,PDATA = (prob data code) 



prob data code: any combination of the following, separated by commas. If 
you specify only one code, you do not need parentheses. 

PSW 

REGS 

SA or SAH 

JPA or LPA or ALLPA 

SPLS 

SUBTASKS 



,STORAGE = (strt addr, end addr) 
,LIST = list addr 



,STRHDR = (hdr addr) 



,STKHDR = hdr list addr 



,SUBPLST = sbp list addr 
,MF = (E,ctrladdr) 



strt addr: RX-type address, or register (2) - (12). 

end addr: RX-type address, or register (2) - (12). 

list addr: RX-type address, or register (2) - (12). 

Note: One or more pairs of addresses may be specified, separated by commas. 

For example: 

STORAGE = (strt addr, end addr, strt addr, end addr) 

hdr addr: RX-type address, or register (2) - (12). 

Note: hdr addr is one or more addresses separated by commas. If you specify 

only one header address as an RX-type address, you do not need the 

parentheses. If you specify one or more registers, then you must code double 

parentheses (one set enclosing each register and one set enclosing the list of 

registers). If STRHDR = (hdr addr) is specified, then STORAGE must also be 

specified. 

hdr list addr: RX-type address, or register (2) - (12). 

Note: If STRHDR = hdr list addr is specified, then LIST must also be 

specified. 

sbp list addr: RX-type address, or register (2) - (12). 

ctrl addr: RX-type address, or register (1) or (2) - (12). 



< 
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The parameters are explained under the standard form of the SNAP macro instruction, with the 
following exceptions: 

,TCB = 'S' 

specifies the task control block of the active task. 

Note: TCB = 'S' causes a dump of the active task if this is the first use of the list form of 
the SNAP macro instruction or if the TCB specified on a previous execute form of the 
SNAP macro instruction was the current TCB or TCB = 'S'. 

,MF = (E,cfr/ addf) 

specifies the execute form of the SNAP macro instruction using a remote control program 
parameter list. 



> 



) 
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SPIE — Specify Program Interruption Exit 



The SPIE macro instruction specifies the address of an interruption exit routine and the 
program interruption types that are to cause the exit routine to be given control. If the 
program interruption types specified can be masked, the corresponding program mask bit in the 
PSW (program status word) is set to 1 . If a maskable interruption is not specified, the 
corresponding bit in the PSW is set to 0. 

Only callers in 24-bit addressing mode can issue the SPIE macro instruction. If a caller in 
31 -bit addressing mode issues a SPIE macro instruction, the caller is abended with a system 
completion code of X'30E'. Callers in 31 -bit addressing mode must use the ESPIE macro 
instruction, which performs the same function as the SPIE macro instruction for callers in both 
24-bit and 31 -bit addressing mode. The ESPIE macro instruction is described in Part II of this 
book. For additional information concerning the relationship between the SPIE and the ESPIE 
macro instructions, see the section on program interruption processing, in Part I. 

Each succeeding SPIE macro instruction completely overrides any previous SPIE macro 
instruction specifications for the task. The specified exit routine is given control in the key of 
the TCB (TCBPKF) when one of the specified program interruptions occurs in any problem 
program of the task. When a SPIE macro instruction is issued from a SPIE exit routine, the 
program interruption element (PIE) is reset (zeroed). Thus, a SPIE exit routine should save any 
required PIE data before issuing a SPIE. If a caller issues an ESPIE macro instruction from 
within a SPIE exit routine, it has no effect on the contents of the PIE. However, if an ESPIE 
macro instruction deletes the last SPIE/ESPIE environment, the PIE is freed and the SPIE exit 
cannot retry. 

If the current SPIE environment is cancelled during SPIE exit routine processing, the control 
program will not return to the interrupted progranrwhen the SPIE program terminates. 
Therefore, if the SPIE exit routine wishes to retry within the interrupted program, a SPIE 
cancel should not be issued within the SPIE exit routine. 

The SPIE macro instruction can be issued by any problem program being executed in the 
performance of the task. The control program automatically deletes the SPIE exit routine when 
the request block (RB) that issued the SPIE macro instruction terminates. If a caller attempts 
to delete a SPIE environment established under a previous RB, the caller is abended with a 
system completion code of X'46D'. 

Note: In MVS/370 the SPIE environment existed for the life of the task. In MVS/XA, the 
SPIE environment is deleted when the request block that issued the macro is deleted. That is, 
when a program running under MVS/XA completes, any SPIE environments created by the 
program are deleted. This might create an incompatibility with MVS/370 for programs that 
depend on the SPIE environment remaining in effect for the life of the task rather than the 
request block 

A PICA (program interruption control area) is created as part of the expansion of SPIE. The 
PICA contains the exit routine's address and a code indicating the interruption types specified 
in SPIE. 

If a SPIE environment was active, the SPIE service routine returns the address of the previous 
PICA in register 1; if an ESPIE environment was active, the SPIE service routine returns the 
address of a fake PICA in register 1. The contents of the fake PICA are unpredictable. If no 
SPIE/ESPIE environment was active, the service routine returns a zero. 
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For more information on the SPIE macro and its control blocks, see the section on program 
interruption processing. 

The standard form of the SPIE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SPIE. 
SPIE 

b One or more blanks must follow SPIE. 

exit addr, (interrupts) exit addr: A-type address, or register (2) - (12). 

interrupts: decimal digits, 1-15, expressed as: 

single values: (2,3,4,7,8,9,10) 
ranges of values: ((2,4),(7,10)) 
combinations: (2,3,4,(7,10)) 



The parameters are explained as follows: 

exit addr -^interrupts) 

specifies the address of the exit routine to be given control when a program interruption 
of the type specified occurs. The interruption types are: 

Number Interruption Type 



1 

2 
3 


Operation 
Privileged operation 
Execute 


4 


Protection 


5 
6 

7 


Addressing 

Specification 

Data 


8 
9 
10 
11 


Fixed-point overflow (maskable) 
Fixed-point divide 
Decimal overflow (maskable) 
Decimal divide 


12 
13 
14 
15 


Exponent overflow 
Exponent underflow (maskable) 
Significance (maskable) 
Floating-point divide 



Notes: 

1. If an exit address is zero or no parameters are specified, the SPIE environment is cancelled. 

2. If a program interruption type is maskable, the corresponding bit is set to 1 when specified 
and to when not specified. Interruption types that are not maskable and not specified above 
are handled by the control program, which forces an abend with the program check as the 
completion code. If an ESTAE-type recovery routine is also active, the SDWA indicates a 
system-forced abnormal termination. The registers at the time of the error are those of the 
control program. 

3. As shown in the table above, interruption types can be designated as one or more single 
numbers, as one or more pairs of numbers (designating ranges of values) , or as any 
combination of the two forms. For example, (4,8) indicates interruption types 4 and 8; 
((4,8)) indicates interruption types 4 through 8. 
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Example 1 



For both ESP IE and SPIE — If you are using vector instructions and an exception of 8, 12, 
13, 14, or 15 occurs, your recovery routine can check the exception extension code (the first 
byte of the two-byte interruption code in the EPIE or PIE) to determine whether the 
exception was a vector or scalar type of exception. 



Operation: Give control to an exit routine for interruptions 1, 5, 7, 8, 9, and 10. DOITSPIE is 
the address of the SPIE exit routine. 

SPIE DOITSPIE, (1,5,7, (8,10) ) 



< 
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SPIE (List Form) 



Use the list form of the SPIE macro instruction to construct a control program parameter list in 
the form of a program interruption control area. 

The list form of the SPIE macro instruction is written as follows: 



b 

SPIE 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede SPIE. 

One or more blanks must follow SPIE. 



exit addr, 
(interrupts), 



exit addr: A- type address. 

interrupts: decimal digits, 1-15, expressed as: 



) 



single values: (2,3,4,7,8,9,10) 
ranges of values: ((2,4),(7,10)) 
combinations: (2,3,4,(7,10)) 



MF = L 



The parameters are explained under the standard form of the SPIE macro instruction, with the 
following exception: 

MF = L 

specifies the list form of the SPIE macro instruction. 
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SPIE (Execute Form) 



A remote control program parameter list, the program interruptions control area (PICA) is used 
in, and can be modified by, the execute form of the SPIE macro instruction. The PICA can be 
generated by the list form of SPIE, or you can use the address of the PICA returned in register 
1 following a previous SPIE macro instruction. If this macro instruction is being issued to 
reestablish a previous SPIE environment, code only the MF parameter. 

The address of the remote control program parameter list associated with any previous SPIE 
environment is returned by the SPIE macro instruction. 

The execute form of the SPIE macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SPIE. 
SPIE 

b One or more blanks must follow SPIE. 

exit addr, exit addr: RX-type address, or register (2) - (12). 

{interrupts), interrupts: decimal digits, 1-15, expressed as: 

single values: (2,3,4,7,8,9,10) 
ranges of values: ((2,4),(7,10)) 
combinations: (2,3,4,(7,10)) 

MF = (E,ctrl addr) Ctrl addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the SPIE macro instruction, with the 
following exception: 

MF = (E,ctrl addr) 

specifies the execute form of the SPIE macro instruction using a remote control program 
parameter list. 

Note: If SPIE is coded with a as the control address, the SPIE environment is cancelled. 
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SPLEVEL - SET and TEST Macro Level 

Specific macro instructions supplied in the MVS/XA macro library are identified as downward 
incompatible (to MVS/370 System Product Version 1 Release 3). Unless the user takes specific 
action, these macros generate downward incompatible statements. It is possible to cause the 
generation of downward compatible expansions of these macros by using the SPLEVEL macro 
instruction. The downward incompatible macro instructions interrogate a global symbol (set by 
SPLEVEL) during assembly to determine the type of expansion to be generated. See the topic 
"Selecting the Macro Level" for additional information concerning the downward incompatible 
macro instructions and Assembler H Version 2 Application Programming: Language Reference 
for information about global set symbols. 

The SPLEVEL macro instruction is written as follows: 

name name: symbol. Begin name in column 1. 

b One or more blanks must precede SPLEVEL. 
SPLEVEL 

b One or more blanks must follow SPLEVEL. 

SET = « n: 1 or 2. 

SET Default: SET = 2 

TEST 



The parameters are explained as follows: 

SET = n 

SET 

TEST 

specifies whether the macro level is being set or tested. 

If SET = n is specified, SPLEVEL processing sets a global set symbol equal to n, where n 
must be 1 or 2. If a user codes one of the downward incompatible macros, one of the 
following macro expansions is generated: 

• the MVS/370 (System Product Version 1 Release 3) macro expansion if n = 1 

• the MVS/XA macro expansion if n = 2 

If SET is specified without n, the SPLEVEL routine uses the default value, which is 2, 
unless the installation has changed the default. 

The TEST option is used to determine the macro level that is in effect. The results of the 
test request are returned to the user in the global set symbol, &SYSSPLV, which is 
defined by "GBLC &SYSSPLV." If TEST is specified and if SPLEVEL SET has not been 
issued during this assembly, SPLEVEL processing puts the default value into the global 
set symbol. If SPLEVEL SET has been issued, the previous value of n or the default 
value is already in the global set symbol. 
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Example 1 

Operation: Select the MVS/370 version of a specific downward incompatible macro instruction. { 

SPLEVEL SET=1 

Example 2 

Operation: Select the MVS/XA version of a specific downward incompatible macro instruction. 

SPLEVEL SET=2 
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STATUS - Change Subtask Status 



| 



The STATUS macro instruction lets the programmer change the dispatchability status of one or 
all of a program's subtasks. For example, the STATUS macro instruction can be used to 
restart subtasks that were stopped when an attention exit routine was entered. 

The STATUS macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede STATUS. 
STATUS 

b One or more blanks must follow STATUS. 

START 
STOP 



) 



,TCB = tcb addr tcb addr: RX-type address, or register (2) - (12). 

,RELATED = value value: Any valid macro keyword specification. 



The parameters are explained as follows: 

START 
STOP 

specifies that the START or STOP count in the task control block specified in the TCB 
parameter will be decreased (for START) or increased (for STOP) by 1. If the TCB 
parameter is not coded, the count is decreased/increased by 1 in the task control blocks 
for all the subtasks of the originating task. 

Note: This parameter does not assure that the subtask(s) is stopped when control is 
returned to the issuer. A subtask can have a "stop deferred" condition that would cause 
that particular subtask to remain dispatchable until stops are no longer deferred. In an 
MP environment, it would be possible to have a task issue the STATUS macro with the 
STOP parameter and resume processing while the subtask (for which the STOP was 
issued) is re-dispatched to another processor. 

,TCB = tcb addr 

specifies the address of a fullword on a fullword boundary containing the address of the 
task control block that is to have its START/STOP count adjusted. (If a register is 
specified, however, the address is of the TCB itself.) If this parameter is not coded, the 
count is adjusted in the task control blocks for all the subtasks of the originating task. 

Note: TCB must reside in 24-bit addressable storage. 

,RELATED = va/we 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 
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Example 1 



Example 2 



Example 3 



The RELATED parameter may be used, for example, as follows: 

STAT1 STATUS STOP , TCB=YOURTCB , RELATED= ( STAT2 , 

•STOP A SUBTASK 1 ) 



STAT2 STATUS START , TCB= YOURTCB , RELATED= ( STAT 1 , 

' START A SUBTASK ' ) 

Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 



Operation: Stop all subtasks. 
STATUS STOP 



Operation: Stop a specific subtask. WHERETCB is a fullword specifying the address of a 
subtask TCB. 

STATUS STOP , TCB=WHERETCB 



Operation: Start a specific subtask. WHERETCB is a fullword specifying the address of a 
subtask TCB. 

STATUS START , TCB=WHERETCB 
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STIMER - Set Interval Timer 

This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The STIMER macro instruction is used to set a timer to a specified time interval (less than or 
equal to 24 hours) or to an interval that will expire at a specified time of day (not to exceed 
24:00:00:00). An optional asynchronous timer completion exit is given control when the time 
interval expires; if no asynchronous timer completion routine is specified, no indication that the 
time interval has expired is provided. Only one time interval per task is in effect at a time, ' 
using STIMER, however, using STIMERM in conjunction with STIMER allows 17 separate 
intervals to be associated with a task. A second STIMER macro instruction issued before the 
first time interval expires overrides the first interval and exit routine. If a timer exit routine 
issues an STIMER macro instruction specifying the same exit routine, an infinite loop might 
result. 



) 



The time interval may be a 'real-time interval' (measured continuously in real time via the clock 
comparator), or a 'task time interval' (measured, only while the task is in execution, via the 
CPU timer). If a real time interval is specified, the task may elect to either continue (REAL) or 
suspend (WAIT) execution during the interval. If the task elects to continue execution, it may 
optionally specify an exit routine to be given control on completion of the time interval. If the 
task elects to suspend execution, it is restarted at the next sequential instruction on completion 
of the time interval. If a task time interval is specified, the task must continue. It may 
optionally specify an exit routine to be given control on completion of the interval. 



The STIMER macro instruction is written as follows: 



name 
b 

STIMER 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede STIMER. 

One or more blanks must follow STIMER. 



REAL 

REAL,exit rtn addr 
TASK 

TASK,exit rtn addr 
WAIT 



exit rtn addr: RX-type address, or register (0) or (2) - (12). 



M 



,BINTVL = stor addr 
,DINTVL = stor addr 
,GMT = stor addr 
,MICVL = stor addr 
,TOD = stor addr 
,TUINTVL = stora<tar 

,ERRET = err rtn addr 



stor addr: RX-type address, or register (1) or (2) - (12). 

Note: The GMT and TOD parameters must not be specified with 

TASK above. 



err rtn addr: RX-type address 
or register (2) - (12). 
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The parameters are explained as follows: 

REAL ( 

REAL,exit rtn addr 

TASK 

TASK,exit rtn addr 
WAIT 

specifies whether the timer interval is a real-time interval (REAL or WAIT) or a task-time 

interval (TASK): 

For REAL, the interval is decreased continuously. If the TOD or GMT parameter is 
coded, the interval expires at the indicated time of day. 

For TASK, the interval is decreased only when the associated task is active. 

For WAIT, the interval is decreased continuously. The task is to be placed in the wait 
condition until the interval expires. 

The exit rtn addr is the address of the timer completion exit routine to be given control 
after the specified time interval expires. The routine does not get control immediately 
when the interval completes, but at some time after the interval completes, depending on 
the system's work load and the relative dispatching priority of the associated task. The 
routine must be in virtual storage when it is required. The exit routine receives control in 
the addressing mode of the caller. The contents of the registers when the exit routine is 
given control are as follows: 

Register Contents 

- 1 Control program information. 1 

2-12 Unpredictable. ^ 

13 Address of a control-program-provided save area. 

14 Return address (to the control program). 

15 Address of the exit routine. 

The exit routine is responsible for saving and restoring registers. The exit routine executes 
as a subroutine, and must return control to the control program. Although timing 
services allows only one active time interval for a task, it does not serialize the use of an 
asynchronous timer completion exit routine. 

,B1NTYL = stor addr 
,DINTVL = stor addr 
,GMT = stor addr 
,MIC VL = stor addr 
,TOD = stor addr 
,TUINTVL = stor addr 

specifies that the time be returned: 

For BINTVL, the address is in virtual storage containing the time interval. The time 
interval is presented as an unsigned 32-bit binary number; the low-order bit has a value of 
0.01 second. 



( 
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For DINTVL, the address is a doubleword on a doubleword boundary in virtual storage 
containing the time interval. The time interval is presented as zoned decimal digits of the 
form: 

HHMMSSth, where: 

HH is hours (24-hour clock) 

MM is minutes 

SS is seconds 

t is tenths of seconds 

h is hundredths of seconds 

For GMT, the address is an 8-byte area containing the Greenwich mean time at which the 
interval is to be completed. The time is presented as zoned decimal digits of the form 
HHMMSSth, as described above under DINTVL. 

For MICVL, the address is a doubleword on a doubleword boundary containing the time 
interval. The time interval is represented as an unsigned 64-bit binary number; bit 51 is 
the low-order bit of the interval value and equivalent to 1 microsecond. 

For TOD, the address is a doubleword on a doubleword boundary containing the time of 
day at which the interval is to be completed. The time of day is presented as zoned 
decimal digits of the form HHMMSSth, as described above under DINTVL. 

For TUINTVL, the address is a fullword on a fullword boundary containing the time 
interval. The time interval is presented as an unsigned 32-bit binary number; the 
low-order bit has a value of one timer unit (approximately 26.04166 microseconds). 

Note: For the DINTVL, GMT, and TOD parameters, the zoned decimal digits are not 
checked for validity. Thus, the specification of invalid digits can result in an ABEND 
0C7, or a time interval different from that desired. 

,ERRET - err rtn addr 

specifies the address of the routine to be given control when the STIMER function cannot 
be performed because of damaged clocks. The STIMER macro will test the return code 
and give control to the specified routine for a non-zero value. The register contents when 
the routine is given control are: 

Register Contents 

- 1 unpredictable 

2-14 unchanged 
15 return code 

If the caller does not specify ERRET, then the STIMER function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) will result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meaning 
Code 

00 Successful completion. 

08 Damaged clocks. 



) 
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Example 1 



Notes: 

1. The time interval specified by an STIMER macro instruction has no relation to the time 
interval specified in an EXEC statement. 

2. If the optional exit routine address and WAIT are not specified, no indication of completion 
of the time interval is provided. 

3. The TTIMER and CPUTIMER macro instructions provide a facility for determining the 
remaining time interval associated with STIMER. 

4. The STIMER macro instruction should not be issued while a BTAM OPEN or LINE OPEN 
operation is in progress, since the BTAM OPEN LINE routines also use STIMER. STIMER 
should not be issued before invoking dynamic allocation because dynamic allocation can also 
issue STIMER. 

5. Specifying a time interval greater than 24 hours and DINTVL (without TOD or GMT), 
BINVTL, MICVL, or TUINVL causes the time interval to be set to 24 hours. 

6. Specifying a time interval greater than 24 hours and DINTVL with TOD or GMT, causes a 
12F abend. 

The priorities of other tasks in the system can also affect the accuracy of the time interval 
measurement. If you code REAL or WAIT, the interval is decreased continuously and can 
expire when the task is not active. After the time interval expires, assuming the task is not in 
the wait condition for any other reasons, the task is placed in the ready condition and competes 
for control with the other ready tasks in the system. The additional time required before the 
task becomes active depends on the relative dispatching priority of the task. 



Operation: Request the user's asynchronous exit routine, located at location EXIT, to receive 
control after the number of hundredths of seconds specified at INTVLONG has elapsed in real 
time. 

STIMER REAL, EXIT ,B INT VL= INTVLONG 
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STIMERM SET - Set Multiple Interval Timer 



The STIMERM SET macro instruction is used to set a timer to a specified time interval (less 
than 24 hours) or to an interval that will expire at a specified time of day (not to exceed 24 
hours). Up to sixteen STIMERM requests per task may be in effect at a time. Note that this 
limit of sixteen does not include time intervals established via the STIMER macro instruction 
or the set DIE function. 

The time interval is a real-time interval, measured continuously. The task may elect to either 
continue (WAIT = NO) or suspend execution (WAIT = YES). If the task elects to continue 
execution, it may optionally specify an exit routine to be given control on completion of the 
time interval. If an exit routine is specified, the task may optionally elect to pass a parameter to 
the exit routine. The optional asynchronous timer completion exit is given control when the 
time interval expires; if no asynchronous timer completion routine is specified, and 
WAIT = YES is not specified, no indication that the time interval has expired is provided. 

The standard form of the STIMERM SET macro instruction is written as follows: 



STIMERM 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede STIMERM. 

One or more blanks must follow STIMERM. 



I 



SET 

,ID = stor addr 
,BINTVL=,ytor addr 
,DINTVL = stor addr 
,GMT = stor addr 
,MlCVL = stor addr 
,TOD = stor addr 
,TUINTVL = stor addr 

,ERRET = err rtn addr 

,WAIT = YES 
,WAIT = NO 

,EXIT = exit rtn addr 



,PARM = stor addr 



.RELATED = value 



stor addr: A-type address or 

stor addr: A-type address or 

stor addr: A-type address or 

stor addr: A-type address or 

stor addr: A-type address or 

stor addr: A-type address or 

stor addr: A-type address or 

err rtn addr: A-type address 

Default: WAIT = NO 



register (2) - (12). 

register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 

or register (2) - (12). 



exit rtn addr: A-type address or register (2) - (12). 

Note: EXIT must not be specified if WAIT = YES is specified. 

stor addr: A-type address or register (2) - (12). 

Note: If PARM is specified, EXIT must be specified and WAIT = YES must not 

be specified. 



The parameters are explained below: 

SET 

This indicates a request to establish a REAL time interval. 

,ID = addr 

specifies the address of a 4-byte area in which the identifier timer service assigns to this 
request will be returned. 
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,BINTVL = stor addr 
JilNTYL^ stor addr 
,GMT ' = stor addr 
MlCVL = stor addr 
,TOD = stor addr 
,TUINTYL = stor addr 

specifies the storage address and format of the time interval: 

For BINTVL, the address of a 4-byte area containing the time interval. The time interval is 
represented as an unsigned 32-bit binary number; the low-order bit has a value of 0.01 second. 

For DINTVL, the address of an 8-byte area in virtual storage containing the time interval. The 
time interval is represented as zoned decimal digits of the form: 

HHMMSSth, where: 

HH is hours (24-hour clock) 

MM is minutes 

SS is seconds 

t is tenths of seconds 

h is hundredths of seconds 

For GMT, the address is an 8-byte area containing the Greenwich mean time at which the 
interval is to be completed. The time is represented as zoned decimal digits of the form 
HHMMSSth, as described previously under DINTVL. 

For MICVL, the address is an 8-byte storage area containing the time interval. The time 
interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the 
interval value and equivalent to 1 microsecond. 

For TOD, the address is an 8-byte storage area containing the time of day at which the interval 
is to be completed. The time of day is represented as zoned decimal digits of the form 
HHMMSSth, as described previously under DINTVL. 

For TUINTVL, the address is a 4-byte area containing the time interval. The time interval is 
represented as an unsigned 32-bit binary number; the low-order bit has a value of one timer 
unit (approximately 26.04166 microseconds). 

Note: For the DINTVL, GMT, and TOD parameters, the zoned decimal digits are not 
checked for validity. Thus, the specification of invalid digits can result in an ABEND 0C7, or a 
time interval different from that desired. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
invoker of the STIMERM function will be abnormally terminated. The specified error 
routine will be entered in the addressing mode of the STIMERM invoker. If the macro 
parameter list or any in-storage parameters are not accessible, the STIMERM invoker will 
be abended regardless of whether or not ERRET has been specified. 
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The register contents when the routine is given control are: 

Contents 



address of a 24-byte STIMERM parameter list 

1 unpredictable 



unpredictable 
2-14 unchanged 

15 return code 

jEXIT = exit rtn addr 

specifies the address of an exit routine to be given asynchronous control after the 
requested timer interval expires. The system's workload and the relative dispatching 
priority of the associated task determine exactly when, after the interval completes, the 
exit routine gets control. The specified exit routine will be entered in the addressing mode 
of the STIMERM invoker. If WAIT = YES is specified, then the EXIT parameter must 
not be specified. 

Exit Routine Interface 

The timer exit routine, established with the EXIT parameter in an STIMERM macro 
instruction, receives control with the following register values: 

RO - control program information 

Rl - points to an 8-byte fetch-protected storage area below the 16Mb line and in the protect key that issued the 
STIMERM SET macro instruction. 



Rl > 

Word 1 

Word 2 



TIMER REQUEST ID 



USER PARAMETER (specified in the PARM keyword) 



) 



R2-R12 - unpredictable 

R13 - address of a 72-byte save area provided by the control program 

R14 - return address (to control program) 

R15 - address of the exit routine 

The exit routine receives control in the addressing mode of the STIMERM issuer. 

,PARM = stor addr 

specifies the address of a 4-byte parameter to be passed to the exit routine when the 
requested timer interval expires. PARM = stor addr must not be specified if WAIT = YES 
is specified. If PARM = stor addr is specified, EXIT = exit rtn addr must also be specified. 

,WAIT=F£S 
,WAIT =NO 

specifies whether the task should be suspended until the requested time interval expires. 
WAIT = YES specifies that the task should be suspended until the requested time interval 
expires. If WAIT = NO is coded, and EXIT is not specified, then no indication of timer 
expiration is given. WAIT = NO is the default. 

,RELATED = va/«e 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 
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When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified is given control. If ERRET is omitted, a 
non-zero return code will result in an ABEND of the STIMERM invoker; 



Hexadecimal 
Code 


Meaning 





The STIMERM service completed successfully. 


8 


All time-of-day clocks in the system are inoperative. 


C 


GMT or TOD value specified exceeds 24 hours. 


10 


Parameters passed to STIMERM are invalid. 


18 


All clock comparators in the system are inoperative. 


1C 


Request would cause the limit of concurrent STIMERM SET requests 
supported for a TASK to be exceeded. 



Example 1 



Usage Notes: 

1 . The time interval specified by an STIMERM macro instruction has no relation to the time 
interval specified in an EXEC statement. 

2. If the optional exit routine address and WAIT = NO are not specified, no indication of 
completion of the time interval is provided. 

3. Specifying a time interval greater than 24 hours and DINTVL, BINVTL, MICVL, or 
TUINVL, causes the time interval to be set to 24 hours. 

4. Specifying a time interval greater than 24 hours with TOD or GMT, causes a 32E abend if 
ERRET is not specified. 

5. All input and output data addresses are treated as full 31 -bit addresses. 

6. The STIMERM SET parameter list may be above or below the 16Mb line. 

7. There is no interaction between the STIMER macro support and the STIMERM SET 
macro support. 

8. An exit routine will be unable to distinguish between the case where PARM = was not 
specified and the case where the specified PARM value was zero. 

9. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abended regardless of whether or not ERRET has been specified. 

10. If multiple asynchronous exits are established, the exit routines may not receive control in 
the same order that the intervals expire. 



Operation: SET a timer to a specified time interval. Specify the address of a 4-byte area in 
which the identifier assigned by the timer service to this request will be returned. Specify that 
control should be given to an asynchronous timer completion exit named TIME when the time 
interval expires. Specify the address of a 4-byte area (containing the time interval represented 
as an unsigned 32-bit binary number) named INTERVAL. Include an error exit routine named 
ERROR. 

STIMERM SET , ID=ADDRESS / BINTVL=INTERVAL ,EXIT=TIME ,ERRET=ERROR 



( 
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Example 2 



Example 3 



Operation: SET a timer to a time interval that specifies the address of a 4-byte area in which 
the identifier assigned by timer service will be returned. Specify the address of a 8-byte area 
(containing the Greenwich mean time at which the interval is to be completed) named 
INTERVAL. Specify that the task should be suspended until the requested time interval 
expires. Include an error exit routine named EXITX. 

STIMERM SET , ID=ADDRESS , GMT=INTERVAL , WAIT=YES , ERRET=EXITX 



Operation: SET a timer to a time interval that specifies the address of a 4-byte area in which 
the identifier assigned by timer service will be returned. Specify the address of an 8-byte area 
(containing the time interval represented as a zoned decimal digit) in register 8. Specify the 
address of a 4-byte parameter to be passed to the exit routine when the requested time interval 
expires. Include the address of an exit error routine in register 9. 

STIMERM SET , ID= ( 7 ) , DINTVL= ( 8 ) , PARM=USERDATA , ERRET= ( 9 ) 



> 
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STIMERM SET - Set Multiple Interval Timer (List Form) 

The list form of the STIMERM SET macro instruction is written as follows: 



b 
STIMERM 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede STIMERM. 

One or more blanks must follow STIMERM. 



Example 1 



SET 
,MF = L 

,RELATED = va/we 



The parameters are explained as follows: 

,MF = L 

specifies the list form of the STIMERM SET macro. If MF = L is not specified, then the 
standard form of the macro is expanded. If MF = L is specified, the only keyword 
allowed is RELATED. 



Operation: Establish a remote STIMERM SET parameter list. 

STIMERM SET,MF=L 



< 
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STIMERM SET — Set Multiple Interval Timer (Execute Form) 

The execute form of the STIMERM SET macro instruction is written as follows: 



STIMERM 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede STIMERM. 

One or more blanks must follow STIMERM. 



SET 

,ID = stor addr 

,BINTVL = stor addr 
,DINTVL = stor addr 
,GMT = stor addr 
,MICVL = stor addr 
,TOD= stor addr 
,TUINTVL = stor addr 

,ERRET = err rtn addr 

,WAIT = YES 
,WAIT = NO 

,EXIT = exit rtn addr 

,PARM = stor addr 

,MF = (E,ctrladdr) 

,RELATED = value 



stor addr: A 



stor addr: 
stor addr: 
stor addr: 
stor addr: 
stor addr: 
stor addr: 



err rtn addr: 



■type address or 

-type address or 
■type address or 
■type address or 
■type address or 
■type address or 
■type address or 

A-type address 



register (2) - (12). 

register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 
register (2) - (12). 

or register (2) - (12). 



exit rtn addr: A-type address or register (2) - (12). 
stor addr: A-type address or register (2) - (12). 
Ctrl addr: A-type address or register (1) - (12). 



Example 1 






The parameters are explained in the standard form of the STIMERM SET macro instruction, 
with the following exception. 

specifies the execute form of the STIMERM SET macro instruction using a remote 
problem program parameter list. If MF = (E,ctrl addr) is not specified, then the standard 
form of the macro is expanded. 



Operation: Establish a timer to a specified time interval specifying the address of a 4-byte area 
in which the identifier assigned to this request by timer service will be returned. Specify the 
address of an 8-byte area (containing the time interval represented as an unsigned 64-bit binary 
number) in register 5. Specify the address of a program to be given asynchronous control after 
the requested timer interval expires. Specify the address of a 4-byte parameter to be passed to 
the exit routine when the requested time interval expires. Include the address of an error 
routine in register 9. 

STIMERM SET,ID=(4) ,MICVL=(5) ,EXIT=ROUTE ,PARM=DATA, X 

MF= ( E , REMOTE ) , ERRET= ( 9 ) 
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STIMERM TEST - Test a Time Interval 

The STIMERM TEST macro instruction is used to test the remaining time interval for a timer 
request established via the STIMERM SET macro instruction. The particular timer request to 
be tested is identified via the ID = parameter, and must have been established by the current 
task. 

If TU is specified, the STIMERM TEST macro instruction causes the control program to 
return the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit 
binary number containing the number of timer units (approximately 26.04166 microseconds per 
unit) remaining in the interval. 

If MIC is specified, the remaining time is returned to the designated 8-byte storage area. Bit 51 
of the area is the low-order bit of the interval value, and is equivalent to approximately 1 
microsecond. 

If the specified (via ID = ) timer request does not exist for the current task, or has expired, the 
storage area designated by TU = or MIC = is set to 0. 

If the specified (via ID = ) timer request exists for the current task, and the calculation of the 
interval remaining results in a negative or zero time interval, the minimum positive interval will 
be returned to the user. If the specified timer request has expired, a zero time interval is 
returned. This allows the user to differentiate the case where the interval has expired, and the 
case where the interval has not yet expired, but the remaining interval is less than or equal to 
zero. 

The standard form of the STIMERM TEST macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

TEST 

,ID = stor addr stor addr: A-type address or register (2) - (12). 

,TU = stor addr stor addr: A-type address or register (2) - (12). 

,MIC = stor addr stor addr: A-type address or register (2) - (12). 

,ERRET = err rtn addr err rtn addr: A-type address or register (2) - (12). 

,RELATED = value 

The parameters are explained below. 

TEST 

This indicates a request to return the remaining time for a request made using the 
STIMERM SET option. 

,ID = stor addr 

specifies the address of a 4-byte area containing the identifier assigned by the timer service 
routine to a particular timer request. 



i 
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) 



,TU = stor addr 
,MIC = stor addr 

specifies that the remaining time in the interval be returned: 

For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary 
number. The low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time is returned in microseconds. The stor addr is the 8-byte area where the 
remaining interval is to be stored. The remaining interval is represented as an unsigned 
64-bit binary number; bit 51 is equivalent to 1 microsecond. 

The stor addr is the area where the remaining interval is to be stored. TU and MIC are 
mutually exclusive. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
STIMERM issuer will be abnormally terminated. The specified error routine will be 
entered in the AMODE of the STIMERM invoker. 



) 



If the macro parameter list or any in-storage parameters are not accessible, the 
STIMERM invoker will be abended regardless of whether or not an ERRET = has been 
specified. 

The register contents when the routine is given control are: 
Register Contents 



0-1 


unpredictable 


2-14 


unchanged 


15 


return code 



,RELATED = va/«e 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 

Return Codes 



When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified, is given control. If ERRET is omitted, a 
non-zero return code results in an abnormal termination of the STIMERM invoker. 



Hexadecimal 
Code 



10 

24 



Meaning 



The STIMERM service has completed successfully. 

All time-of-day clocks in the system are inoperative. 

Parameters passed to STIMERM are invalid. 

An invalid STIMERM ID number (either 0, or greater than the highest ID 
assigned by the system) has been specified. 



) 
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Usage Notes: 

1. All input and output addresses are treated as full 31 -bit addresses. 

2. The STIMERM TEST parameter list may be above or below the 16Mb line. 

3. There is no interaction between the TTIMER macro support and the STIMERM TEST 
macro support. A time interval established via the STIMER macro cannot be tested with 
the STIMERM TEST macro instruction. Similarly, a time interval established via the 
STIMERM SET macro cannot be tested with the TTIMER macro instruction. 

4. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abended regardless of whether or not an ERRET = has been specified. 



( 



Example 1 



Example 2 



Operation: Test the remaining time interval for a timer request established with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area (register 4) from which the 
identifier assigned to this request by the timer service will be obtained. Specify that the time be 
returned in a 4-byte area as an unsigned 32-bit binary number at the address labeled 
INTERVAL. Include the address of an exit error routine called XYZ. 

STIMERM TEST,ID=(4) ,TU= INTERVAL ,ERRET=XYZ 



Operation: Test the remaining time interval for a timer request established with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area at the address labeled ADDR 
from which the identifier assigned to this request by timer service will be obtained. Specify that 
the time be returned in microseconds in a 8-byte area as an unsigned 64-bit binary number at 
the address labeled INTERVAL. Include the address of an exit error routine called 
ERRORADD. 

STIMERM TEST, ID=ADDR,MIC=INTERVAL,ERRET=ERRORADD 



( 



< 
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\ 



) 



) 



STIMERM TEST — Test a Time Interval (List Form) 

The list form of the STIMERM TEST macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

TEST 
,MF = L 

.RELATED = value 



The parameters are explained as follows: 

,MF = L 

specifies a list form macro. If MF = L is not specified, then the standard form of the 
macro is expanded. If MF = L is specified, the only keyword allowed is RELATED = 



Example 1 



Operation: Establish a remote STIMERM TEST or CANCEL parameter list. 

STIMERM TEST,MF=L 
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STIMERM TEST — Test a Time Interval (Execute Form) 

The execute form of the STIMERM TEST macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

TEST 

,ID = storaddr stor addr: A-type address or register (2) - (12). 

,TU = stor addr stor addr: A-type address or register (2) - (12). 

,MIC = stor addr stor addr: A-type address or register (2) - (12). 

,ERRET = err rtn addr err rtn addr: A-type address or register (2) - (12). 

,MF = (E,cf/7 addr) ctrl addr: A-type address or reg (0), or (2) - (12). 

.RELATED = value 



The parameters are explained under the standard form of the STIMERM TEST macro 
instruction with the following exception: 

,MF-(E,cfr/a/<fr) 

specifies an execute form of the STIMERM STEST macro instruction using a remote 
problem program parameter list. If MF = (E,ctrl addr) is not specified, then the standard 
form of the macro is expanded. 



Example 1 



Operation: Test the remaining time interval for a timer request established with the STIMERM 
SET macro instruction, specifying the address of a 4-byte area at the address named ADDR in 
which the identifier assigned by timer service to this request will be returned. Specify that 
register 3 will point to the appropriate list. Specify that the time be returned in microseconds in 
a 8-byte area as an unsigned 64-bit binary number at the address named INTERVAL. Include 
the address of an exit error routine called ERR. 

STIMERM TEST,ID=ADDR / MIC=INTERVAL,MF=(E / (3) ) / ERRET=ERR 



1 
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STIMERM CANCEL - Cancel a Timer Request 



) 



The STIMERM CANCEL macro instruction is used to cancel a specific timer request, (or all) 
of the current task's timer requests established via the STIMERM SET macro instruction. The 
ID = parameter is used to identify the timer request(s) to be cancelled. If a specific timer 
request is to be cancelled, then the remaining time interval for that request may optionally be 
returned to a storage area designated by the TU or MIC parameters. 

If TU is specified, the STIMERM CANCEL macro instruction causes the control program to 
return the amount of time remaining to the designated 4-byte storage area as an unsigned 32-bit 
binary number containing the number of timer units (approximately 26.04166 microsecond 
units) remaining in the interval. 

If MIC is specified, the remaining time is returned to the designated 8-byte storage area. Bit 51 
of the area is equivalent to approximately 1 microsecond. 

If the specified (via ID = ) timer request exists for the current task, and the calculation of the 
interval remaining results in a negative or zero time interval, the minimum positive interval will 
be returned to the user. If the specified timer request has expired, a zero time interval is 
returned. This allows the user to differentiate the case where the interval has expired, and the 
case where the interval has not yet expired, but the remaining interval is less than or equal to 
zero. 

If a non-zero time is returned when ID = is specified, any exit routine associated with the 
specified timer request is cancelled. 

If an invalid STIMERM ID (either 0, or greater than the highest ID assigned by the system) 
has been specified, the ERRET routine will be entered, or if ERRET is not specified, the 
STIMERM CANCEL invoker will be abnormally terminated. 

The standard form of the STIMERM CANCEL macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

CANCEL 

,ID = s tor addr stor addr: A-type address or register (2) - (12). 

,ID = ALL 

,TU = stor addr stor addr: A-type address or register (2) - (12). 

,MIC= stor addr stor addr: A-type address or register (2) - (12). 

,ERRET = err rtn addr err rtn addr: A-type address or register (2) - (12). 

,RELATED = va/we 



The parameters are explained below: 

CANCEL 

This indicates a request to cancel and optionally return the remaining time for a timer 
request. 
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,ID = stor addr 
,ID = ALL 

specifies the address of a 4-byte area containing the identifier assigned by the timer service 
to a particular timer request. ID = ALL results in all the current task's timer request(s) 
established by STIMERM SET being cancelled. If ALL is specified, no remaining time 
interval is returned. 

If ID = ALL is specified, then neither TU nor MIC may be specified. 

,TU 

,MIC = stor addr 

specifies that the remaining time in the interval be returned: 

For TU, the time is returned to the specified 4-byte area as an unsigned 32-bit binary 
number. The low-order bit is approximately 26.04166 microseconds (one time unit). 

For MIC, the time is returned to the specified 8-byte area. Bit 51 of the area is equivalent 
to approximately 1 microsecond. 

The stor addr is the area where the remaining interval is to be stored. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the STIMERM function 
cannot be performed. If this parameter is omitted and an error is encountered, the 
STIMERM issuer will be abnormally terminated. The specified error routine will be 
entered in the addressing mode of the STIMERM invoker. If the macro parameter list or 
any in-storage parameters are not accessible, the STIMERM invoker will be abnormally 
terminated regardless of whether or not an ERRET routine is specified. 

The register contents when the routine is given control are: 
Register Contents 



0-1 


unpredictab 


2-14 


unchanged 


15 


return code 



,RELATED = ra/we 

specifies information used to self document macro instructions by 'relating' functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid macro 
keyword expression. 

Return Codes 

When control is returned, register 15 contains one of the following return codes. Note that for 
non-zero return codes, the ERRET routine if specified, is given control. If ERRET is omitted, 
a non-zero return code will result in an ABEND of the STIMERM invoker. 



< 
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Hexadecimal 
Code 



Meaning 



10 

24 



The STIMERM service has completed successfully. 

All time-of-day clocks in the system are inoperative. The CANCEL has 
been performed, but no remaining time interval will be returned. 

Parameters passed to STIMERM are invalid. 

An invalid STIMERM ID (either 0, or greater than the highest ID assigned 
by the system has been specified). 



) 



Example 1 



Example 2 



Example 3 



) 



Usage Notes: 

1. All input and output addresses are treated as full 31 -bit addresses. 

2. The STIMERM CANCEL parameter list may be above or below the 16Mb line. 

3. There is no interaction between the TTIMER CANCEL macro support and the STIMERM 
CANCEL macro support. A time interval established via the STIMER macro cannot be 
cancelled with STIMERM CANCEL. 

4. If the macro parameter list or any in-storage parameters are not accessible, the STIMERM 
invoker will be abnormally terminated regardless of whether or not an ERRET routine is 
specified. 

5. If the STIMERM CANCEL specifies (via ID = ) a timer request that was established with 
the WAIT = YES parameter, the task will not be taken out of the wait condition. 



Operation: Cancel a timer request established with a STIMERM SET macro instruction, 
specifying the address of a 4-byte area named ADDRESS containing the identifier assigned by 
the timer service. The time interval remaining should be returned as an unsigned 32-bit binary 
number in a 4-byte area called INTERVAL. An exit error routine named ERROR is also be 
specified. 

STIMERM CANCEL , ID=ADDRESS , TU=INTERVAL , ERRET=ERROR 



Operation: Cancel a timer request established with a STIMERM SET macro instruction, 
specifying the address of a 4-byte area named PLACE containing the identifier assigned by the 
timer service. The time interval remaining should be returned in a 8-byte area called 
INTERVAL. An exit error routine named EXITA is also be specified. 

STIMERM CANCEL , ID=PLACE ,MIC=INTERVAL ,ERRET=EXITA 



Operation: Cancel all the timer requests established with STIMERM SET macro instruction for 
the current task. 

STIMERM CANCEL, ID=ALL 
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STIMERM CANCEL (List Form) 

The list form of the STIMERM CANCEL macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

CANCEL 
,MF = L 

,RELATED = va/we 



The parameters are explained as follows: 

,MF = L 

specifies a list form of the macro instruction. If MF = L is not specified, then the 
standard form of the macro is expanded. If MF = L is specified, the only keyword allowed 
is RELATED = . 



Example 1 



Operation: Establish the appropriate storage for the EXECUTE form of the STIMERM 

CANCEL macro instruction. . 

1 

STIMERM CANCEL, MF=L ^ 



( 
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STIMERM CANCEL (Execute Form) 

The execute form of the STIMERM CANCEL macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede STIMERM. 
STIMERM 

b One or more blanks must follow STIMERM. 

CANCEL 

,\T> = stor addr stor addr: A-type address or register (2) - (12). 
,ID = ALL 

,TU = stor addr stor addr: A-type address or register (2) - (12). 

,MIC = stor addr stor addr: A-type address or register (2) - (12). 

,ERRET = err rtn addr err rtn addr: A-type address or register (2) - (12). 

,MF = (E,ctrl addr) Ctrl addr: A-type address or register (2) or (2). 

,RELATED = any value 



The parameters are explained under the standard form of the STIMER CANCEL macro 
instruction with the following exception: 

specifies an execute form using a remote problem program parameter list. If MF = (E,ctrl 
addr) is not specified, then the standard form of the macro is expanded. 



Example 1 



Operation: Cancel the timer request established with a STIMER SET macro instruction. 
Specify the address of a 4-byte identifier named ADDRESS, and that the time interval 
remaining be returned as an unsigned binary number in a 4-byte area named INTERVAL. 
Specify an error exit routine named ERROR. 

STIMERM CANCEL, ID=ADDRESS ,TU=INTERVAL ,MF= (E , (0) ) ,ERRET=ERROR 
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SYNCH — Take a Synchronous Exit to a Processing Program 

I 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The SYNCH macro instruction makes it possible for a problem state program to take a 
synchronous exit to a processing program. On entry to the processing program, the high-order 
bit, bit 0, of register 14 is set to indicate the addressing mode of the issuer of the SYNCH 
macro. If bit is 0, the issuer is executing in 24-bit addressing mode; if bit is 1, the issuer is 
executing in 31 -bit addressing mode. The SYNCH routine analyzes a PRB (program request 
block) and schedules execution of the requested program. After the processing program has 
been executed, the program that issued the SYNCH macro instruction regains control. 

The standard form of the SYNCH macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SYNCH. 
SYNCH 

b One or more blanks must follow SYNCH. 

entry point addr entry point addr: RX-type address, or register (2) - (12) or (15). 

.RESTORE = NO Default: RESTORE = NO 

,RESTORE = YES 

,AMODE = 24 Default: AMODE = CALLER. 

,AMODE = 31 Note: AMODE = DEFINED can be specified only d 

,AMODE = DEFINED if the entry point address is provided in m 

,AMODE = CALLER a register. 



The parameters are explained as follows: 

entry point addr 

specifies the address of the entry point of the processing program to receive control. 

,RESTORE = NO 
,RESTORE = YES 

specifies whether registers 2-13 are to be restored when control returns to the caller. 

,AMODE = 24 
,AMODE = 31 
,AMODE = DEFINED 
,AMODE = CALLER 

specifies the addressing mode in which the requested program is to receive control. 

If AMODE = 24 is specified, the requested program will receive control in 24-bit 
addressing mode. 

If AMODE = 31 is specified, the requested program will receive control in 31 -bit 
addressing mode. 

If AMODE = DEFINED is specified, the user must provide the entry point using a 
register and not an RX-type address. The requested program will receive control in the 



( 



322 Supervisor Services and Macro Instructions 



Example 1 



addressing mode indicated by the high order bit of the entry point address. If the bit is 
off, the requested program will receive control in 24-bit addressing mode; if the bit is set, 
the requested program will receive control in 31 -bit addressing mode. 

If AMODE = CALLER is specified, the requested program will receive control in the 
addressing mode of the caller. 



Operation: Take a synchronous exit to PROGRAM A. Do not restore registers 2-13 when 
control returns. 



LOAD EP=PROGRAMA,DCB=LIBl 

LR R8,R0 

SYNCH (R8) ,RESTORE=NO 



Load desired program 
Obtain the entry point 



Example 2 



Example 3 



Example 4 



Example 5 



) 



Operation: Take a synchronous exit to a program labeled SUBRTN and restore registers 2-13 
when control returns. 

SYNCH SUBRTN, RESTORE=YES 



Operation: Take a synchronous exit to the program located at the address given in register 
and restore registers 2-13 when control returns. Indicate that this program is to execute in 
24-bit addressing mode. 

SYNCH (8) ,RESTORE=YES,AMODE=24 



Operation: Take a synchronous exit to the program located at the address given in register 8 
and restore registers 2-13 when control returns. Indicate that this program is to receive control 
in the addressing mode defined by the high-order bit of its entry point address. 

SYNCH ( 8 ) , RESTORE=YES , AMODE=DEFINED 



Operation: Take a synchronous exit to the program located at the address given in register 8 
and restore registers 2-13 when control returns. Indicate that this program is to receive control 
in the addressing mode as the caller. 

SYNCH ( 8 ) , RESTORE=YES , AMODE=CALLER 
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SYNCH (List Form) 



Example 1 



The list form of the SYNCH macro instruction is used to construct a control program 
parameter list. 

The list form of the SYNCH macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SYNCH. 
SYNCH 

b One or more blanks must follow SYNCH. 



.RESTORE = NO Default: RESTORE = NO 

,RESTORE = YES 

,AMODE = 24 Default: AMODE = CALLER 

AMODE = 31 
AMODE = DEFINED 
,AMODE = CALLER 



,MF = L 



The parameters are explained under the standard form of the SYNCH macro instruction, with 
the following exception: 



,MF = L 

specifies the list form of the SYNCH macro instruction. 



Operation: Use the list form of the SYNCH macro instruction to specify that registers 2-13 are 
to be restored when control returns from executing the SYNCH macro instruction and that the 
addressing mode of the program is to be defined by the high-order bit of the entry point 
address. Assume that the execute form of the macro instruction specifies the program address. 

SYNCH , RESTORE=YES , AMODE=DEFINED , MF=L 
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SYNCH (Execute Form) 



Example 1 



) 



The execute form of the SYNCH macro instruction uses a remote control program parameter 
list that can be generated by the list form of SYNCH. 

The execute form of the SYNCH macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede SYNCH. 
SYNCH 

b One or more blanks must follow SYNCH. 

entry point addr entry point addr: RX-type address, or register (2) - (12) or (15). 

,RESTORE = NO Default: RESTORE = NO 
,RESTORE = YES 

,AMODE = 24 Default: AMODE = CALLER 

, AMODE = 3 1 Note: AMODE = DEFINED can be specified only if the entry point 

,AMODE = DEFINED address is provided in a register. 

,AMODE = CALLER 

,MF = (E,ctrl addr) Ctrl addr: RX-type address or register (1), (2) - (12). 



The parameters are explained under the standard form of the SYNCH macro instruction, with 
the following exception: 

,MF = (E,ctrladdr) 

specifies the execute form of the SYNCH macro instruction. 



Operation: Use the execute form of the SYNCH macro instruction to take a synchronous exit 
to the program located at the address given in register 8 and restore registers 2-13 when control 
returns. Indicate that the program is to receive control in the same addressing mode as the 
caller and that the parameter list is located at SYNCHL2. 

SYNCH (8) ,RESTORE=YES,AMODE=CALLER,MF=(E,SYNCHL2) 
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TIME — Provide Time and Date 

The TIME macro instruction causes the control program to return either the local time of day 
and date, the Greenwich mean time of day and date, or the contents of the TOD clock. The 
time of day and date are only as accurate as the corresponding information entered by the 
operator, and the system response time. 

Unless STCK is specified, the date is returned in register 1 as packed decimal digits of the form 

OCYYDDDF, where: 

C is a digit representing centuries beyond the twentieth. In the years 1900 through 1999, the macro will return a 

value of C = 0. 
YY is the last two digits of the year 
DDD is the day of the year 
F is a 4-bit sign character that allows the data to be unpacked and printed 

The time of day, based on a 24-hour clock, is returned in different forms, as designated by the 
parameters shown below. For the DEC, BIN, and TU parameters, the time of day is returned 
in register 0. For the MIC and STCK parameters, the time of day and TOD clock contents 
respectively are stored at the specified address. 

The TIME macro instruction is written as follows: 

The parameters are explained as follows: 



name 
b 

TIME 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede TIME. 

One or more blanks must follow TIME. 



DEC 
BIN 

TU 

MIC,stor addr 
STCK,stor addr 

,ZONE = LT 
,ZONE = GMT 

,ERRET = err rtn addr 



Default: DEC 

stor addr: RX-type address or register (0) or (2) - (12). 



Default: ZONE = LT 

Note: This parameter has no meaning if STCK above is specified. 

err rtn addr: A- type address, or register (2) - (12). 



DEC 

BIN 

TU 

MIC ,stor addr 
STCK ,stor addr 

specifies that the time of day or TOD clock contents be returned: 

For DEC, the time of day is returned in register as packed decimal digits, without a 
sign, of the form 



HHMMSSth, where: 

HH is hours (24-hour clock) 

MM is minutes 

SS is seconds 

t is tenths of seconds 

h is hundredths of seconds 



< 
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For BIN, the time of day is returned in register as an unsigned 32-bit binary number. 
The low-order bit is equivalent to 0.01 seconds. 

For TU, the time of day is returned in register as an unsigned 32-bit binary number. 
The low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time of day is returned in microseconds. The stor addr is the address of an 
8-byte area in storage with bit 5 1 equivalent to one microsecond. 

For STCK, the contents of the TOD clock is returned as an unsigned 64-bit fixed-point 
number, where bit 51 is equivalent to 1 microsecond. The stor addr is the address of an 
8-byte area in storage. Register 1 does not contain the date on return. 

Notes: 

1. The resolution of the time-of-day clock is model dependent. See Principles of Operation 
for an explanation of the rate advancement. 

2. stor addr must be a 24-bit address. 

,ZONE = LT 
,ZONE = GMT 

specifies that the local time and date (LT) or the Greenwich mean time and date (GMT) 
is to be returned. 

,ERRET = err rtn addr 

specifies the address of the routine to be given control when the TIME function cannot be 
performed because of damaged clocks. The TIME macro will test the return code and 
give control to the specified routine for a non-zero value. The register contents when the 
routine is given control are: 

Register Contents 



0-1 


unpredictable 


2-14 


unchanged 


15 


return code 



If the caller does not specify ERRET, then the TIME function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) will result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meaning 
Code 

00 Successful completion 

08 Damaged clocks 
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Operation: Request the system to store the time-of-day clock in the address pointed to by 
register 2. The user's routine TIMEERR is to receive control if no usable time-of-day clock 
exists in the system. 

TIME STCK, (2) ,ERRET=TIMEERR 



328 Supervisor Services and Macro Instructions 



) 



TTIMER - Test Interval Timer 

The TTIMER macro instruction is used to test the timer interval established by an STIMER 
macro instruction. It is also used to cancel the remaining time interval. 

If TU is specified or assumed, the TTIMER macro instruction causes the control program to 
return in register the amount of time remaining in a timer interval previously set by an 
STIMER macro instruction. The time remaining is returned as an unsigned 32-bit binary 
number specifying the number of timer units (approximately 26.04166 microsecond units) 
remaining in the interval. If a time interval has not been set or has already expired, register 
contains 0. 

If MIC is specified, the remaining time is returned to the doubleword area specified in the 
address. Bit 51 of the area is the low-order bit of the interval value and equivalent to 1 
microsecond. If a time interval has not been set or has already expired the area is set to 0. 

Note: The resolution of the timer is model dependent. See Principles of Operation for 
additional details concerning the timer facility. 

The TTIMER macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede TTIMER. 
TTIMER 

b One or more blanks must follow TTIMER. 

CANCEL 

,TTJ Default: TU 

,MlC,stor addr stor addr: RX-type address, or register (0) or (2) - (12). 

,ERRET = m- rtn addr err rtn addr: RX-type address, or register (2) - (12). 

The parameters are explained as follows: 

CANCEL 

specifies that the remaining time interval and any exit routine are to be canceled. If the 
time interval has already expired, the CANCEL option has no effect and a value of zero 
time remaining is returned. In this case, a specified exit will still receive control. If a 
non-zero time remaining is returned when the CANCEL option is specified, any exit 
routine is canceled. If CANCEL is not designated, the unexpired portion of the time 
interval remains in effect. 

If WAIT was coded in the STIMER macro instruction that established the interval, the 
task is not taken out of the wait condition and CANCEL is ignored. 



w 



TTIMER — Test Interval Timer 329 



,TU 

,MIC ,stor addr 

specifies that the remaining time in the interval be returned: 

For TU, the time is returned in register as an unsigned 32-bit binary number. The 
low-order bit is approximately 26.04166 microseconds (one timer unit). 

For MIC, the time is returned in microseconds. The stor addr is the doubleword area on 
a doubleword boundary where the remaining interval is to be stored. 

,ERRET = errrtnaddr 

specifies the address of the routine to be given control when the TTIMER function 
cannot be performed because of damaged clocks. The TTIMER macro will test the 
return code and give control to the specified routine for a non-zero value. The register 
contents when the routine is given control are: 

Register Contents 



0-1 


unpredictable 


2-14 


unchanged 


15 


return code 



If the caller does not specify ERRET, then the TTIMER function will return only on 
successful completion (return code 0). If ERRET is not specified, failure due to damaged 
clock(s) will result in the abnormal termination of the caller. 

When control is returned, register 15 contains one of the following return codes: 



Hexadecimal 
Code 


Meaning 




00 
08 


Successful completion 
Damaged clocks 


Usage Notes 







i 



Example 1 



1. Time intervals established via the STIMERM SET macro instruction cannot be tested 
or cancelled with the TTIMER macro instruction. 



Operation: Cancel the task's current time interval. The time remaining, if any, should be 
returned in timer units in register 0. 

TTIMER CANCEL, TU 



( 
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WAIT - Wait for One or More Events 

The WAIT macro instruction is used to inform the control program that performance of the 
active task cannot continue until one or more specific events, each represented by a different 
ECB (event control block), have occurred. Bit and bit 1 of each ECB must be set to before 
it is used. The control program takes the following action: 

• For each event that has already occurred (each ECB is already posted), the count of the 
number of events is decreased by 1. 

• If the number of events is by the time the last event control block is checked, control is 
returned to the instruction following the WAIT macro instruction. 

• If the number of events is not by the time the last ECB is checked, control is not returned 
to the issuing program until sufficient ECBs are posted to bring the number to 0. Control 
is then returned to the instruction following the WAIT macro instruction. 

The WAIT macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede WAIT. 
WAIT 

b One or more blanks must follow WAIT. 

event nmbr, event nmbr: symbol, decimal digit, or register (0) or (2) - (12). 

Default: 1 
Value range: 0-255 

ECB = ecb addr ecb addr: RX-type address, or register (1) or (2) - (12). 

ECBLIST = ec6 list addr ecb list addr: RX-type address, or register (1) or (2) - (12). 

,LONG = NO Default: LONG = NO 

,LONG = YES 

,RELATED = value value: Any valid macro keyword specification. 

The parameters are explained as follows: 

event nmbr, 

specifies the number of events waiting to occur. 

ECB = ecb addr 

ECBLIST = ecb list addr 

specifies the address of an ECB on a fullword boundary or the address of a virtual storage 
area containing one or more consecutive fullwords on a fullword boundary. Each 
fullword contains the address of an ECB; the high order bit in the last fullword must be 
set to 1 to indicate the end of the list. 

The ECB parameter is valid only if the number of events is specified as one or is omitted. 
The number of ECBs in the list specified by the ECBLIST form must be equal to or 
greater than the specified number of events. 

,LONG = NO 
,LONG = YES 

specifies whether the task is entering a long wait (YES) or a regular wait (NO). 
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,RELATED = value 

specifies information used to self-document macro instructions by "relating" functions or 
services to corresponding functions or services. The format and contents of the 
information specified are at the discretion of the user, and may be any valid coding 
values. 

The RELATED parameter is available on macro instructions that provide opposite 
services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and 
LOAD/DELETE), and on macro instructions that relate to previous occurrences of the 
same macro instructions (for example, CHAP and ESTAE). 

The RELATED parameter may be used, for example, as follows: 

WAITl WAIT 1,ECB=ECB,RELATED=( RESUME 1, 
'WAIT FOR EVENT 1 ) 



RESUME 1 POST 



ECB , , RELATED= ( WAITl , 
' RESUME WAITER ' ) 



Note: Each of these macro instructions will fit on one line when coded, so there is no 
need for a continuation indicator. 

CAUTION 

A job step with all of its tasks in a WAIT condition is terminated upon 
expiration of the time limits that apply to it. 

Example: You have previously initiated one or more activities to be completed asynchronously 
to your processing. As each activity was initiated, you set up an ECB in which bits and 1 
were set to 0. You now wish to suspend your task via the WAIT macro instruction until a 
specified number of these activities have been completed. 

Completion of each activity must be made known to the system via the POST macro 
instruction. POST causes an addressed ECB to be marked complete. If completion of the 
event satisfies the requirements of an outstanding WAIT, the waiting task is marked ready and 
will be executed when its priority allows. 



Example 1 



Example 2 



Operation: Wait for one event to occur (with a default count). 

WAIT ECB=WAITECB 
WAITECB DC F'O' 



Operation: Wait for 2 events to occur. 

WAIT 2,ECBLIST=LISTECBS 



LISTECBS 



DC A(ECB1) 

DC A(ECB2) 

DC X'80' 

DC AL3(ECB3) 
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Example 3 

Operation: Enter a long wait for a task. 

WAIT 1,ECBLIST=LISTECBS,L0NG=YES 



LISTECBS DC A(ECB1) 

DC A(ECB2) 

DC X'80 1 

DC AL3(ECB3) 



> 
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WTL - Write To Log 



The WTL macro instruction causes a message to be written to the system log. The message can 
include any character that can be used in a C-type (character) DC statement, and is assembled 
as a variable-length record. 

Note: The exact format of the output of the WTL macro instruction varies depending on the 
job entry subsystem (JES2 or JES3) that is being used, the output class that is assigned to the 
log at system initialization, and whether DLOG is in effect for JES3. In JES3, system log 
entries are preceded by a 23 -character prefix that includes a time stamp and routing 
information. If the combined prefix and message exceeds 126 characters, the log entry is split 
at the first blank or comma encountered when scanning backward from the 126th character of 
the combined prefix and message. See Operations: JES3 Commands for information about the 
format of the log entry when using JES3. 

The standard form of the WTL macro instruction is written as follows: 



b 
WTL 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede WTL. 

One or more blanks must follow WTL. 



msg 



msg: Up to 126 characters. 



The parameter is explained as follows: 

'msg' 

specifies the message to be written to the system log. The message must be enclosed in 
apostrophes, which will not appear in the system log. See Figure 43 for a list of the 
printable EBCDIC characters passed to display devices or printers. 

Note: If the msg text exceeds 126 characters, truncation occurs at the last embedded blank 
before the 126th character; when there are no embedded blanks, truncation occurs after the 
126th character. 



Example 1 



Example 2 



Operation: Write a message to the system log. 

WTL 'THIS IS THE STANDARD FORMAT FOR THE WTL MACRO 1 

Operation: Write a message constructed in the list form of WTL. 
WTL MF=(E,(R2)) 



< 
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WTL (List Form) 



) 



The list form of the WTL macro instruction is used to construct a control program parameter 
list. The message parameter must be provided in the list form of the macro instruction. 

The list form of the WTL macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede WTL. 
WTL 

b One or more blanks must follow WTL. 

'msg' msg: Up to 126 characters. 
,MF = L 



The 'msg' parameter is explained under the standard form of the WTL macro instruction. A 
description of the MF parameter follows: 

,MF = L 

specifies the list form of the WTL macro instruction. 

Note: If msg text exceeds 126 characters, truncation occurs at the last embedded blank before 
the 126th character; when there are no embedded blanks, truncation occurs after the 126th 
character. 
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WTL (Execute Form) 



The execute form of the WTL macro instruction uses a remote control program parameter list. 
The parameter list can be generated by the list form of WTL. You cannot modify the message 
in the execute form. 

The execute form of the WTL macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede WTL. 
WTL 

b One or more blanks must follow WTL. 

MF = (E,cfr/ addr) Ctrl addr: RX-type address, or register (1) or (2) - (12). 



This parameter is explained as follows: 

MF = (E,ctrl addr) 

specifies the execute form of the WTL macro instruction. This form uses a remote 
control program parameter list. 



i 
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WTO — Write to Operator 



The WTO macro instruction causes a message to be written to one or more operator consoles. 
WTO processing uses register 15. 

The standard form of the WTO macro instruction is written as follows: 



b 
WTO 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede WTO. 

One or more blanks must follow WTO. 



msg 
('text') 
('text', line type) 



msg: Up to 125 characters. 

The permissible line types and lengths are shown below: 

C 34 char 

L 70 char 

D 70 char 

DE 70 char 
E 

Default: D 

The maximum number of each line type allowed in a single WTO instructions 
is: 



,ROUTCDE = (routing code) 
,DESC = (desc code) 



1 Ctype 

2 L type 
10 D type 

1 DE type 

1 E type 

The maximum total number of line types allowed in one instruction is 10. 

routing code: decimal digit from 1 to 16. The routing code is one or more 
codes, separated by commas. 

desc code: decimal digit from 1 to 16. The desc code is one or more codes, 
separated by commas. 



The parameters are explained as follows: 

'msg' 
{'text*) 

{'text', line type) 

specifies the message or multiple-line message to be written to one or more operator 
consoles. 



) 



The first format is used to write a single-line message to the operator. In the format, the 
message must be enclosed in apostrophes, which do not appear on the console. It can 
include any character that can be used in a character (C-type) DC instruction. When a 
program issues a WTO macro instruction, the control program translates the text; only 
standard printable EBCDIC characters are passed to the display devices as shown in 
Figure 43. All other characters are replaced by blanks. Unless the console has dual-case 
capability, lowercase characters are converted to uppercase by the display station or 
printer and displayed or printed as uppercase characters. The message is assembled as a 
variable-length record. 
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D 



DE 



E 



The second and third formats are used to write a multiple-line message to the operator. 
The message can be up to ten lines long; the system truncates the message at the end of 
the tenth line. The ten-line limit does not include the control line (message IEE9321I), as 
explained under line type C below. 

Note: If the second format is coded without repetition, for example, {'text 1 ), the message 
appears as a single-line message. 

The text is one line of the multiple-line message. A line consists of a character string 
enclosed in apostrophes (which do not appear on the operator console). Any character 
valid in a C-type DC instruction can be coded. The maximum number of characters 
depends. on which line type is specified. 

Note: The left most three bytes of register zero must be zero for a multiple-line message. 
The user must ensure that this is done. 

The line type defines the type of information contained in the "text" field of each line of 
the message: 



indicates that the "text" parameter is the text to be contained in the control line of the 
message. The control line normally contains a message title. C may only be coded for 
the first line of a multiple-line message. If this parameter is omitted and descriptor code 9 
is coded, the system generates a control line (message IEE932I) containing only a message 
identification number. The control line remains static during framing operations on a 
display console (provided that the message is displayed in an out-of-line display area). 
Control lines are optional. 



indicates that the "text" parameter is a label line. Label lines contain message heading 
information; they remain static during framing operations on a display console (provided 
that the message is displayed in an out-of-line display area). Label lines are optional. If 
coded, lines must either immediately follow the control line or another label line or be the 
first line of the multiple-line message if there is no control line. Only two label lines may 
be coded per message. 



indicates that the "text" parameter contains the information to be conveyed to the 
operator by the multiple-line message. During framing operations on a display console, 
the data lines are paged. 



indicates that the "text" parameter contains the last line of information to be passed to 
the operator. 



indicates that the previous line of text was the last line of text to be passed to the 
operator. The "text" parameter, if any, coded with a line type of E is ignored. 
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,ROUTCDE = routing code 

specifies the routing code(s) to be assigned to the message. 

The routing codes are: 



1 


Master console action 


9 


System security 


2 


Master console information 


10 


System error/maintenance 


3 


Tape pool 


11 


Programmer information 


4 


Direct access pool 


12 


Emulators 


5 


Tape library 


13 


Reserved for customer use 


6 


Disk library 


14 


Reserved for customer use 


7 


Unit record pool 


15 


Reserved for customer use 


8 


Teleprocessing control 


16 


Reserved for future expansion 



Note: Routing codes 1, 2, 3, 4, 7, 8, and 10 cause hard copy of the message when display 
consoles are used or more than one console is active. All other routing codes may go to 
hard copy as a SYSGEN option or as a result of a VARY HARDCPY command. 

,DESC = (desc code) 

specifies the message descriptor code(s) to be assigned to the message. Descriptor codes 1 
through 6 and descriptor code 1 1 are mutually exclusive. Codes 7 through 10 can be 
assigned in combination with any other code. 

The descriptor codes are: 



) 



1 System failure 7 

2 Immediate action required 8 

3 Eventual action required 9 

4 System status 10 

5 Immediate command response 1 1 

6 Job status 12-16 



Application program/processor 
Out-of-line message 
Operator request 
Dynamic status displays 
Critical eventual action requested 
Reserved for future use 







Note: All WTO messages with descriptor codes of 1, 2, or 11 are action messages that 
have an @ sign printed before the first character. This indicates a need for operator 
action. 

Messages with descriptor code 7 are deleted at end of job step. 

Support for queuing messages with descriptor code 8 is by console id only. 

On operator consoles that support color, descriptor codes determine the color in which a 
message should be displayed. The colors used are described in Operations: System Commands. 

The message processing facility cannot suppress messages with descriptor codes 1, 2, 3, 5 
(except for responses from MONITOR JOBNAMES, MONITOR SESS, and MONITOR 
STATUS commands), and 11. Messages with any other descriptor codes can be suppressed if 
they have been identified by an id or prefix in SYS1.PARMLIB member MPFLSTxx. 

If both the ROUTCDE and DESC parameters are omitted and the message is not a single-line 
message, the routing code specified in the OLDWTOR parameter of the system generation 
CONSOLE macro instruction is assigned, and a default of 7 is assigned as the descriptor code. 
If the OLDWTOR sysgen option is omitted, all routing codes and a descriptor code of 7 are 
assigned. Routing codes should be used with MLWTO messages. If DESC is specified with no 
ROUTCDE, the message will be queued to the hardcopy log by default. 
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Example 1 



Example 2 



When control is returned, general register 1 contains the identification number (24 bits and 
right-justified) assigned to the message. This number can be used to delete the message when it 
is no longer needed. 



Return codes from execution of a WTO using the multiple-line feature are as follows: 



Hexadecimal 
Code 

00 

04 



08 
0C 



Meaning 

No errors encountered. 

Number of lines passed was 0; request is ignored. Number of lines passed was greater than 10; only 10 
lines are processed. Message text length for a line was less than 1; all lines up to error line are 
processed. 

ID passed in register does not match any on queue. Request is ignored. 

Invalid line type. An end has been forced at the point of the error except if the first line is an E line, in 
which case the request is ignored. 



Return codes from execution of a WTO are as follows: 



Hexadecimal 
Code 

30 



Meaning 

Required resource for routing code 1 1 was not available. Request is ignored for routing code 11. If any 
other routing code is specified, the request is processed. 



Operation: Write a WTO message to all active consoles. 

WTO 'NDP00005 ENDED 1 , X 

ROUTCDE= (1,2,3,4, 5 , 6,7,8,9, 10 , 11 , 12 , 13 , 14 , 15 , 16 ) , X 
DESC=(4) 



Operation: Write a multiple-line message to the master console if the master is receiving 
routing code 2 and to any other console receiving routing code 2. 



WTO ('text l',D), DATA LINE 

('text 2',DE), DATA END LINE 
ROUTCDE= ( 2 ) , DESC= ( 4 ) 



< 
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WTO (List Form) 



The list form of the WTO macro instruction is used to construct a control program parameter 
list. 

The list form of the WTO macro instruction is written as follows: 



b 
WTO 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede WTO. 

One or more blanks must follow WTO. 



msg 
('text') 



msg: Up to 125 characters. 

The permissible line types and text lengths are shown below: 



C 34 char 

L 70 char 

D 70 char 

DE 70 char 
E 

Default: D 

The maximum number of each line type allowed in a single WTO instructions 
is: 



,ROUTCDE = (routing code) 
,DESC = (desc code) 
,MF = L 



1 

2 

10 

1 

1 



C type 
L type 
D type 
DEtype 
E type. 



The maximum total number of line types allowed in one instruction is 10. 

routing code: decimal digit from 1 to 16. The routing code is one or more 
codes, separated by commas. 

desc code: decimal digit from 1 to 16. The desc code is one or more codes, 
separated by commas. 



) 



The parameters are explained under the standard form of the WTO macro instruction, with the 
following exception: 

,MF = L 

specifies the list form of the WTO macro instruction. 
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WTO (Execute Form) 



Example 1 



The execute form of the WTO macro instruction uses a remote control program parameter list. 
The parameter list can be generated by the list form of WTO. The message cannot be modified 
in the execute form of the macro instruction. 

The execute form of the WTO macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede WTO. 
WTO 

b One or more blanks must follow WTO. 

MF-(E,ctrl addr) Ctrl addr: RX-type address, or register (1) or (2) - (12). 



This parameter is explained as follows: 

MF = (E,ctrladdr) 

specifies the execute form of the WTO macro instruction using a remote control program 
parameter list. 



Operation: Write a message with a pre-built parameter list pointed to by register 1 . 

WTO MF=(E,(1)) 
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1 



WTOR - Write to Operator with Reply 






gr 



This macro can be assembled compatibly between MVS/XA and MVS/370 through the use of 
the SPLEVEL macro instruction. Default processing will result in an expansion of the macro 
that operates only with MVS/XA. See the topic "Selecting the Macro Level" for additional 
information. If your program is to execute in 31 -bit addressing mode, you must use the 
MVS/XA version of this macro instruction. 

The WTOR macro instruction causes a message requiring a reply to be written to one or more 
operator consoles and the hardcopy log. The macro instruction also provides the information 
required by the control program to return the reply to the issuing program. 

The standard form of the WTOR macro instruction is written as follows: 



name name: symbol. Begin name in column 1 . 

b One or more blanks must precede WTOR. 
WTOR 

b One or more blanks must follow WTOR. 

'msg ' msg: Up to 122 characters. 

,reply addr reply addr: A-type address, or register (2) - (12). 

,reply length reply length: symbol, decimal digit, or register (2) - (12). The minimum length 

is 1; the maximum length is 115 when the operator enters REPLY id, 'reply' 
and 119 when the operator enters R id, 'reply'. 

,ecb addr ecb addr: A-type address, or register (2) - (12). 

,ROUTCDE = {routing code) routing code: decimal digit from 1 to 16. The routing code is one or more 

codes, separated by commas. 



The parameters are explained as follows: 



msg 

specifies the message to be written to the operator's console. The message must be 
enclosed in apostrophes, which do not appear on the console. It can include any 
character that can be used in a character (C-type) DC instruction. When a program 
issues a WTO macro instruction, the control program translates the text; only the 
standard printable EBCDIC characters shown in Figure 43 are passed to the display 
devices. All other characters are replaced by blanks. Unless the console has dual-case 
capability, lowercase characters are converted to uppercase by the display station or 
printer and displayed or printed as uppercase characters. The message is assembled as a 
variable-length record. 

Note: All WTOR messages are action messages. An indicator is printed before the first 
character of an action message to indicate a need for operator action. 

,reply addr 

specifies the address in virtual storage of the area into which the control program is to 
place the reply. The reply is left-justified at this address. 

,reply length 

specifies the length, in bytes, of the reply message. 



WTOR — Write to Operator with Reply 343 



,ecb addr 

specifies the address of the event control block (ECB) to be used by the control program 
to indicate the completion of the reply and the id of the replying console. After the 
control program receives the reply, the ECB appears as follows: 

Offset Length(bytes) Contents 

1 Completion code 

1 2 Reserved 

3 1 Console id in hexadecimal 

,ROUTCDE = (routing code) 

specifies the routing code(s) to be assigned to the message. 

The routing codes are: 



1 


Master console action 


9 


System security 


2 


Master console information 


10 


System error/maintenance 


3 


Tape pool 


11 


Programmer information 


4 


Direct access pool 


12 


Emulators 


5 


Tape library 


13 


Reserved for customer use 


6 


Disk library 


14 


Reserved for customer use 


7 


Unit record pool 


15 


Reserved for customer use 


8 


Teleprocessing control 


16 


Reserved for future expansion 



When control is returned, general register 1 contains the identification number (24 bits and 
right-justified) assigned to the message. This number can be used to delete the message when a 
reply is no longer needed. 

Ignored Parameters I 

The parameter DESC — (desc code) is meaningless if coded since all WTOR messages are 
assigned descriptor codes of 7 (application program/processor). 

Example 1 

Operation: Write a WTOR message to all active consoles. 

WTOR 'THIS IS WTOR NUMBER 001 ' , REPLY, 18 ,ECB1 , X 

ROUTCDE= ( 1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10 , 11 , 12 , 13 , 14 , 15 , 16 ) 



( 
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WTOR (List Form) 



The list form of the WTOR macro instruction is used to construct a control program parameter 
list. The message parameter must be provided in the list form. 

The list form of the WTOR macro instruction is written as follows: 



b 
WTOR 

b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede WTOR. 

One or more blanks must follow WTOR. 



) 



msg 



.reply addr 



,reply length 



,ecb addr 

,ROUTCDE = (routing code) 



msg: Up to 122 characters. 
reply addr: A-type address. 

reply length: symbol or decimal digit. The minimum length is 1; the maximum 
length is 115 when the operator enters REPLY id, 'reply' and 119 when the 
operator enters R id, 'reply'. 

ecb addr: A-type address. 

routing code: decimal digit from 1 to 16. The routing code is one or more 
codes, separated by commas. 



,MF = L 



The parameters are explained under the standard form of the WTOR macro instruction, with 
the following exception: 

,MF = L 

specifies the list form of the WTOR macro instruction. 
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WTOR (Execute Form) 



The execute form of the WTOR macro instruction uses a remote control program parameter 
list. The parameter list can be generated by the list form of WTOR. 

The execute form of the WTOR macro instruction is written as follows: 



name 
b 
WTOR 

b 



name: symbol. Begin name in column 1. 
One or more blanks must precede WTOR. 

One or more blanks must follow WTOR. 



,repfy addr 
,reply length 



,ecb addr 
,MF = (E,ctrl addr) 



reply addr: RX-type address, or register (2) - (12). 



reply length: symbol, decimal digit, or register (2) - (12). The minimum length 
is 1; the maximum length is 115 when the operator enters REPLY id, 'reply' 
and 119 when the operator enters R id, 'reply'. 

ecb addr: RX-type address, or register (2) - (12). 

Ctrl addr: RX-type address, or register (1) or (2) - (12). 



The parameters are explained under the standard form of the WTOR macro instruction, with 
the following exception: 

specifies the execute form of the WTOR macro instruction using a remote control 
program parameter list. The parameter list must be aligned on a fullword boundary. The 
list form of WTOR provides this alignment. 
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XCTL — Pass Control to a Program in Another Load Module 

If your program is to execute in 31 -bit addressing mode, you must use the MVS/XA version of 
this macro instruction. 

The XCTL macro instruction causes control to be passed to a specified entry name in another 
load module; the entry name must be a member name, an alias in a directory of a partitioned 
data set, or must have been specified in an IDENTIFY macro instruction. The control 
program brings the load module containing the entry name into storage if a usable copy is not 
already available. XCTL handles the setting of the addressing mode when passing control to 
this entry name. The control program reassigns the storage occupied by the load module that 
issued the XCTL if that module is no longer required. The program executing the XCTL 
macro instruction is logically removed as a subprogram of the program (system or user) that 
placed the issuer of XCTL into execution. 

No return is made to the program issuing the XCTL macro instruction; the use count for the 
load module containing the XCTL macro instruction is decremented by 1. A return to the 
program that placed the issuer of XCTL into execution is required for successful completion of 
the task. For this reason, registers 2 through 14, the program interruption control area, and the 
program mask must be restored to the state that existed when the load module received control 
before the XCTL macro instruction can be issued. If the specified entry cannot be located, the 
task is abnormally terminated. 

On entry to the program specified in the XCTL macro, the high-order bit, bit 0, of register 14 is 
set to indicate the addressing mode of the issuer of the macro. If bit is 0, the issuer is 
executing in 24-bit addressing mode; if bit is 1, the issuer is executing in 31 -bit addressing 
mode. 

The standard form of the XCTL macro instruction is written as follows: 

name name: symbol. Begin name in column 1 . 

b One or more blanks must precede XCTL. 
XCTL 

b One or more blanks must follow XCTL. 

(regl), regl and reg2: decimal digits in the order 2 through 12. 

{regl, regl), 

EP = entry name entry name: symbol. 

EPLOC = enrry name addr entry name addr: A-type address or register (2) - (12). 

DE = /«f entry addr list entry addr: A-type address, or register (2) - (12). 

,DCB = deb addr deb addr: A-type address, or register (2) - (12). 

,LSEARCH = NO Default: LSEARCH = NO 

,LSEARCH=YES 

The parameters are explained as follows: 

(regl), 
(regl,reg2), 

specifies the register or range of registers to be restored from the save area at the address 
contained in register 13. 
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EP = entry name 

EPLOC = entry name addr 

DE = list entry addr 

specifies the entry name, the address of the entry name, or the address of a 60-byte list 
entry for the entry name that was constructed using the BLDL macro instruction. If 
EPLOC is coded, the name must be padded to eight bytes, if necessary. 

If an unauthorized program issues the XCTL macro instruction and the DE parameter 
specifies an entry in an authorized library, the program-supplied DE information is 
ignored for integrity reasons. Instead, contents management uses the BLDL macro 
instruction to construct a new list entry containing the DE information for the XCTL. 
The DE information supplied by an unauthorized program will also be ignored if the 
XCTL macro instruction is requesting access to a program or library that is controlled by 
the System Authorization Facility. 

Note: The task structure must not be changed via an ATTACH or DETACH between 
the issuance of the BLDL and the issuance of the ATTACH for the module, or an abend 
106 with a return code of 15 might result. 

,DCB = deb addr 

specifies the address of the opened data control block for the partitioned data set 
containing the entry name described above. This parameter must indicate the same DCB 
used in the BLDL mentioned above. The DCB must not be defined in the program 
issuing the XCTL macro instruction. 

If the DCB parameter is omitted or if DCB = is specified when the XCTL macro 
instruction is issued by the job step task, the data sets referred to by either the STEPLIB 
or JOBLIB DD statement are first searched for the entry name. If the entry name is not 
found, the link library is searched. 

If the DCB parameter is omitted or if DCB = is specified when the XCTL macro 
instruction is issued by a subtask, the data sets associated with one or more data control 
blocks referred to by the TASKLIB operand of previous ATTACH macro instructions in 
the subtasking chain are first searched for the entry point name. If the entry point name 
is not found, the search is continued as if the XCTL had been issued by the job step task. 

Note: DCB must reside in 24-bit addressable storage. 

,LSEARCH = NO 
,LSEARCH = YES 

specifies whether (YES) or not (NO) you want the search limited to the job pack area and 
the first library in the normal search sequence. 

Note: Do not use register 1 as a pointer to the parameter list passed by the module that issues 
XCTL. Use the execute form of the XCTL and pass the parameters explicitly using the 
PARAM keyword. 
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Example 1 



Operation: Pass control via the address of the entry name (XCTLEP), and have registers 2-12 
restored. Let the system determine the copy of the module to be used. 

XCTL (2,12) ,EPLOC=XCTLEP 



) 
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XCTL (List Form) 



Two parameter lists are used in an XCTL macro instruction: a control program parameter list 
and an optional problem program parameter list. Only the control program parameter list can 
be constructed in the list form of XCTL. Address parameters to be passed in a parameter list 
to the problem program can be provided using the list form of the CALL macro instruction. 
This parameter list can be referred to in the execute form of XCTL. 

The list form of the XCTL macro instruction is written as follows: 



name 
b 

XCTL 
b 



name: symbol. Begin name in column 1 . 
One or more blanks must precede XCTL. 

One or more blanks must follow XCTL. 



EP = entry name, 

EPLOC = entry name addr, 

DE = list entry addr, 

DCB = deb addr, 

LSEARCH = NO, 
LSEARCH = YES, 



SF = L 



entry name: symbol. 

entry name addr: A-type addresses. 

list entry addr: A-type address. 

deb addr: A-type address. 

Default: LSEARCH = NO 



The parameters are explained under the standard form of the XCTL macro instruction, with the 
following exception: 

SF = L 

specifies the list form of the XCTL macro instruction. 

Note: Coding the LSEARCH parameter causes a parameter list to be created that is different 
from the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 
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XCTL (Execute Form) 



) 



Two parameter lists are used in the XCTL macro instruction: a control program parameter list 
and problem program parameter list. Either or both of these parameter lists can be remote and 
can be referred to, and modified by, the execute form of XCTL. If only the problem program 
parameter list is remote, parameters that require the control program parameter list cause that 
list to be constructed inline as part of the macro expansion. If only the control program 
parameter list is remote, no problem program parameters can be specified. 

The execute form of the XCTL macro instruction is written as follows: 



name name: symbol. Begin name in column 1. 

b One or more blanks must precede XCTL. 
XCTL 

b One or more blanks must follow XCTL. 



(regl), regl and reg2: decimal digits or RX-type addresses, and in the order 2 

(regl, regl), through 12. 

EP = entry name, entry name: symbol. 

EPLOC = entry name addr, entry name addr: RX-type address of register (2) - (12). 

DE = list entry addr, list entry addr: RX-type address, or register (2) - (12). 

DCB = deb addr, deb addr: RX-type address, or register (2) - (12). 

PARAM = (addr), addr: RX-type address, or register (2) - (12). 

PARAM = (addr),N~L = 1, addr is one or more addresses, separated by commas. For example, 

PARAM = (addr, addr, addr) 

LSEARCH = NO, Default: LSEARCH = NO 
LSEARCH = YES, 

MF = (E,prob addr) prob addr: RX-type address, or register (1) or (2) - (12). 

SF = (E,ctrl addr) Ctrl addr: RX-type address, or register (2) - (12) or (15). 
MF = (E,prob addr),SF = (E,ctrl addr) 



The parameters are explained under the standard form of the XCTL macro instruction, with the 
following exceptions: 

F ARAM = (addr) 

PARAM = (addr), VL = 1 

specifies address(es) to be passed to the called program. Each address is expanded inline 
to a fullword on a fullword boundary, in the order designated. Register 1 contains the 
address of the first parameter when the program is given control. If this parameter is not 
coded, register 1 is not altered unless the LSEARCH parameter is coded. If LSEARCH 
is coded, the contents of register 1 are unpredictable. 

VL = 1 should be designated only if the called program can be passed a variable number 
of parameters. VL = 1 causes the high-order bit of the last address parameter to be set to 
1 ; the bit can be checked to find the end of the list. 

LSEARCH = NO 
LSEARCH = YES 

specifies whether (YES) or not (NO) you want the search limited to the job pack area and 
to the first library in the normal search sequence. If LSEARCH is specified and PARAM 
is not specified, the contents of register 1 are unpredictable. 
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MF = (E,probaddr) 

SF = (E,ctrl addr) 

MF = (%prob addr),SF = (E,ctrl addr) 

specifies the execute form of the XCTL macro instruction. This form uses a remote 
problem program parameter list, a remote control program parameter list, or both. 

Note: Coding the LSEARCH parameter causes a parameter list to be created that is different 
from the list created when LSEARCH is omitted. If you code LSEARCH in either the list or 
execute form of the macro instruction, you must code it in both forms. 
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//JOBLIB DD statements 28 
//STEPLIB DD statements 28 
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A-type address 124 

ABDUMP symptom area 64 

ABEND completion code, field containing 65 

ABEND dump 

changing dump options 69 

requesting 68 

suppressing 69 
ABEND macro instruction 

description 126 

examples 128 

syntax 126 

use of 61 
abends 

handling 61 

interrupting scheduled 188 
abnormal conditions, processing and detecting 53 
abnormal termination 

caused by failure to remove a subtask 161 

caused by misuse of ENQ 173 

of a task 126 

providing an ESTAI to handle 66 

requesting 61 

ways to avoid with ENQ/DEQ 46 

when an entry name is not located 227 

when deleting a SPIE/ESPIE environment 54 

when issuing CLOSE 82 
action messages 339, 343 
adding a load module entry name 220 
address space priority 10 
addressing mode 

See also AMODE program attribute 

affect on BAL and BALR 16 

bitinthePSW 16 

changing 

example 18 

using BSM or BASSM 17 

using LINK 222 

considerations when passing control 17 

indicator 

in a PDS entry 15 

in an entry point address 17, 28 

of a loaded module 33 

of alias entry points 40 

of SPIE routines 54 

specifying 

in source code 15 



using linkage editor control cards 15 
aliases 

addressing mode of 40 

establishing 40 
allocating virtual storage 213 
AMDPRDMP service aid, printing and formatting 

ABEND dumps 69 
AMODE program attribute 

See also addressing mode 

changing 

example 17 

using BSM or BASSM 17 

indicator 

in a PDS entry 15 

in an entry point address 17, 28 

purpose 15 

specifying 

in source code 15 

using linkage editor control cards 15 

use in load processing 227 

values 1 6 
analyzing return codes 24 
ASM (auxiliary storage manager) 107 
Assembler H 15 
asynchronous 

exit routine 220 
ATTACH macro instruction 

addressing mode considerations 28, 129 

creating subpools 78 

description 129 

DPMOD parameter 10 

ECB parameter, use of 12 

ESTAI parameter, use of 63 

ETXR parameter, use of 12 

example 135 

execute form 137 

GSPL parameter 78 

GSPV parameter 78 

list form 136 

LPMOD parameter 10 

requesting subpool ownership 78 

return codes 134 

SHSPL parameter 78 

SHSPV parameter 78 

specifying subpools 78 

SPLEVEL macro, use of 129 

standard form 130 

syntax 

execute form 137 
list form 136 
standard form 130 

SZERO parameter 78 

TASKLIB parameter 28, 29 

use of 9, 19, 28 
authorization checking, RACF 50 
authorization code for a loaded module 33 
auxiliary storage manager (ASM) 107 
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avoiding an interlock condition 49 



B 



BAL instruction 16 
BALR instruction 16 
BAS instruction 16 
base register 

establishing 6 

use of 6 
BASR instruction 16 
BASSM instruction 17, 36 
BLDL macro instruction, use of 31, 35, 36 
branch and link (BAL) instruction 16 
branch and link instruction, register form (BALR) 16 
branch and save (BAS) instruction 16 
branch and save and set mode (BASSM) instruction 17 
branch and save instruction, register form (BASR) 16 
branch and set mode (BSM) instruction 17 
branch instructions 

BAL 16 

BALR 16 

BAS 16 

BASR 16 

BASSM 17 

BSM 17 

use of 36 

using with XCTL, danger of 38 
branching table, use in analyzing return codes 24 
bringing a load module into virtual storage 28, 227 
BSM instruction 17 



142 



139 



CALL macro instruction 

addressing mode considerations 

description of 139 

example 140 

execute form 

list form 141 

standard form 

syntax 

of execute form 

of list form 141 

of standard form 
use of 22, 23, 33, 36 
called programs 
definition of 3 
entry address 3 
first action to take 5 
calling program 
definition of 3 
return address 3 
save area 5 

address 3 
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139 



how used 5 

saving registers of 5 
calling sequence identifier 40 
cancel a timer request 317 
cell pool 

creating 145 

deleting 145 

obtaining 75, 145 

returning 145 

services 145 
cells 75 

chaining save areas 7 
changing the dispatching priority 143 
CHAP macro instruction 

description of 143 

example 144 

syntax 143 

use of 1 1 
characters printed on an MCS console 113 
check RACF authorization 248 
checking 

resource authorization 201 
CHNGDUMP command 69 
codes 

authorization 33 

completion 60 

descriptor 114 

message routing 114 

reason 60 
coding macro instructions 122, 123 
communicating with the system operator 113 
completed ECBs, list of 197 
completion codes, changing 60 
concatenated data sets 29 
concurrent requests for resources 

limiting 44 
continuation lines in macro parameter fields 125 
control 

See also passing control 

returning 25, 27, 37 
control points 

definition 51 
control program linkage conventions 3 
controlling virtual storage 76 
conventions 

for passing control 8, 19 

for receiving control 8 
CPOOL macro instruction 

description 145 

example 148 

execute form 150 

list form 149 

standard form 145 

syntax 

of execute form 150 

of list form 149 

of standard form 145 

use of 75 
CPU timer, obtaining value of 151 
CPUTIMER macro instruction 
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description of 151 

example 152 

relationship to STIMER macro 

return codes 152 

syntax 151 
creating 

a cell pool 145 

a subpool 78 

a task 9, 129 

an ESPIE environment 181 

an EVENTS table 194 
critical eventual action message 115 
CVTDCB byte 120 
CVTMVSE bit 120 



151 
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DAE 

See dump analysis and elimination 
data control block 

deleting load modules that contain 82 

for SNAP dumps 69 
data security 50 
data sets, dump 69 
date and time of day, requesting 111 
DCB parameter 31 
DD statements required for dumps 68 
DE parameter 31 

debugging aids for calling sequences 40 
decimal digit term in macro instruction description 124 
default priority 10 
DELETE macro instruction 

description 153 

example 154 

lowering the responsibility count 82 

relationship to LOAD macro 153 

return codes 154 

syntax 153 
deleting 

a cell pool 145 

a load module 153 

an ESPIE environment 181 

an EVENTS table 194 

operator messages 117,171 
DEQ macro instruction 

description of 155 

example 158 

execute form 160 

list form 159 

return code area 1 57 

return codes 48, 157 

rules for using 42 

standard form 155 

syntax 

of execute form 160 

of list form 159 

of standard form 155 

use of 42, 46 



descriptor codes 114 
DETACH macro instruction 

description 161 

example 1 62 

return codes 162 

syntax 161 
detaching a subtask 161 
determining 

status of RACF protection 267 

the ESPIE environment 181 

which system is executing 120 
directory entry, PDS 15 
directory search 29 
dispatching priority 

assigning 10 

changing 143 
DIV (data-in-virtual) macro instruction 

linear data set 83 

performance considerations 105 

programming example 99 

reason codes 97 

retain mode 90, 92, 93, 94 

return codes 97 

rules for invoking 96 

rules for use in a task 96 

services of 
access 87 
identify 87 
map 88 
reset 92 
save 90 
unaccess 95 
unidentify 95 
unmap 93 

syntax 163 

use of 83 
DOM macro instruction 

description of 171 

example 172 

syntax 171 

use of 117 
downward incompatible macro instructions 1 19, 297 
DPMOD parameter on ATTACH 10 
DPRTY parameter on the EXEC statement 10 
dump analysis and elimination (DAE) 

providing information for 64 
dumping services 68 
dumps 

ABEND 68 

data sets for 69 

indexes in SNAP dumps 70 

operator's effect on 69 

requesting 68 

SNAP 68, 69 

summary 70 

symptom 69 

types a problem program can request 68 
duplicate 

names in unique task libraries 31 

requests for a resource 45 
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dynamic load module structure 
advantages of 19 
description of 18, 19 



E 



12, 13, 41 



180 



174 



17, 227 
33 



ECB (event control block) 
description of 41 
initializing 196 
list of completed 196 
parameter of ATTACH 
setting 246 
end-of-task exit routine 13 
ENQ macro instruction 
description 173 
example 45, 178 
execute form 180 
list form 179 
return code area 177 
return codes 47, 177 
rules for using 42, 173 
standard form 174 
syntax 

of execute form 
of list form 179 
of standard form 
use of 36, 42 
entry point 
adding 40 
address 

AMODE indicator 
of a loaded module 
specifying 3 
identifier 40 
identifying 22 
using aliases 40 
EP parameter 30 

EPIE (extended program interruption element) 
EPLOC parameter 30 
error processing 59, 61-63 
ESD (external symbol dictionary), AMODE/RMODE 

indicators 1 5 
ESPIE environment 
deleting 54, 181 
determining 181 
establishing 54, 181 
ESPIE macro instruction 
description 181 
examples 

of ESPIE RESET 184 
of ESPIE SET 183 
of ESPIE TEST 185 
of the execute form 187 
of the list form 186 
execute form 187 
list form 186 
options 

RESET 56, 183 



57 



SET 56, 181 

TEST 56, 184 
return codes 

from ESPIE RESET 183 

from ESPIE SET 182 

from ESPIE TEST 185 
syntax 

of ESPIE RESET 183 

of ESPIE SET 181 

of ESPIE TEST 184 

of the execute form 187 

of the list form 186 
use of 53 
using 56 
establishing 

a base register 6 
an ESPIE environment 181 
ESTAE macro instruction 

addressing mode considerations 188 

description 188 

example 191 

execute form 193 

list form 192 

return codes 191 

SPLEVEL macro, use of 188 

standard form 188 

syntax 

of the execute form 193 

of the list form 192 

of the standard form 188 
use of 63 
ESTAE recovery routine 
how to use 63 
interface to 64 

pointer to parameter list created by 65 
retry processing 67 
ESTAI recovery routine 
how to use 66 
interface to 67 
retry processing 67 
ETXR parameter of ATTACH, use of 12 
event 

control block 

See ECB 
signalling completion of 41, 246 
EVENTS macro instruction 
description 194 
example 200 
parameter list 197 
SPLEVEL macro, use of 194 
syntax 194 
use of 41, 196 
events table 

creating 194, 196 
deleting 194, 196 
format of 196 
exclusion name lists 155, 173 
exclusive resource control 44 
EXEC statement, DPRTY parameter 10 
execute form of macro instructions 121 
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execution of load modules 19 
exit routine 

asynchronous 220 

end-of-task 13, 126 

establishing ESTAEs 188 

functions performed by 58 

register contents on entry 58 

specifying 53 

using serially reusable resources 42 
explicit requests for virtual storage 73 
extended PIE (program interruption element) 57 
extended SPIE macro instruction 

See ESPIE macro instruction 
extended STAE 

See ESTAE recovery routine 
external symbol dictionary (ESD), AMODE/RMODE 
indicators 15 







fake PICA 57 

fast path resource authorization checking 

finding 

a load module 29 

a save area 6 
FRACHECK macro instruction 

chart of parameters by release 203 

description 201 

execute form 206 

list form 205 

return codes 204 

standard form 201 

syntax 

of standard form 201 
of the execute form 206 
of the list form 205 

use of 51 
frames 

assigning 107 

repossessing 107 
freeing virtual storage 82, 207 
FREEMAIN macro instruction 

description 207 

example 210 

execute form 212 

list form 211 

return codes 210 

standard form 207 

syntax 

of the execute form 212 

of the list form 211 

of the standard form 207 

use of 73 
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GETMAIN macro instruction 

addressing mode considerations 

creating subpools 78 

description 213 

example 217 

execute form 219 

list form 218 

LOC parameter 74 

return codes 216 

standard form 213 

syntax 

of the execute form 219 

of the list form 218 

of the standard form 213 

types of 74 

use of 73, 74 
gigabytes 15 

global resource serialization 44, 155, 173 
global resources 43, 44 
global symbol 297 
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handling abends 61 



IDENTIFY macro instruction 

description 220 

example 221 

return codes 221 

syntax 220 

use of 40 
IEECVXIT 1 14 
IHASDWA mapping macro 64 
immediate action message 115 
implicit requests for virtual storage 
inclusion name lists 155, 173 
inline parameter list, use of 22 
interface 

to a retry routine 67 

to an ESTAI routine 67 
interlock 

avoiding 49 

illustration of 49 
interruptions 

See program interruption 
interval timing, establishing 111 
introduction to supervisor services 



79 
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job library 

reason for limiting size of 

use of 28 

when to define 31 
job pack area (JPA) 29 
job step task, creating 9 
JPA (job pack area) 29 



31 







last word in parameter list, how to indicate 4 

length of a loaded module 33 

library 

description of 29 

search 29 
limit priority 10, 11 
link library 28 
LINK macro instruction 

addressing mode considerations 28 

description 222 

example 224 

execute form 226 

list form 225 

standard form 222 

syntax 

of the execute form 226 

of the list form 225 

of the standard form 222 

use of 28,33,35 

when to use 82 
link pack area (LP A) 29 
linkage 

considerations for MVS/XA 16 

conventions 3 

editor 15 

registers 3 
list form of macro instructions 121 
lists 

of completed ECBs 197 

of SYSTEM inclusion resource names 155 

of SYSTEMS exclusion resource names 155 
load list area 29 
LOAD macro instruction 

description 227 

example 229 

execute form 231 

indicating addressing mode 28 

list form 230 

relationship to DELETE macro 153 

standard form 227 

syntax 

of the execute form 231 

of the list form 230 

of the standard form 227 



use of 28, 33, 36 

when to use 82 
load module 

adding an entry name 220 

addressing mode 33 

aliases 40 

authorization code 33 

bringing into virtual storage 227 

characteristics of 18 

deleting 1 53 

entry point address 33 

execution 19 

how to avoid getting an unusable copy 32 

length 33 

location 28 

more than one version 30 

names 40 

passing control to 222 

releasing control 153 

responsibility count 33, 38, 227 

searching for 29 

structure types 18 

use count 34 

using an existing copy 32 
loading 

registers and passing control 20 

virtual storage 108, 232, 242 
LOC parameter on the GETMAIN macro 74 
local resource 43 
location of a load module 28 
long wait 42 
LPA (link pack area) 29 
LPMOD parameter on ATTACH 10 



M 



machine check, recovery 59 
macro instructions 

addressing mode considerations 120-121 
coding 122, 123 
downward incompatible 119 
expansion 119 
forms of 

execute 80, 121 

list 80, 121 

standard 80, 121 
level of, selecting 119-120, 129, 188, 194, 301, 343 
reenterable form 79 
requiring caller to be in 24-bit mode 120 
requiring MVS/XA version in 31 -bit mode 121 
restrictions on using 119 
sample 123 
terms used in description of 

A-type address 124 

decimal digit 124 

default 124 

register 124 
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113 



40 



115 



RX-type address 124 
symbol 123 

ways of passing parameters 

when can be used 119 
MCS consoles, characters displayed 
megabytes 15 
member names, establishing 
message 

critical eventual action 

deleting 117, 171 

descriptor codes 114 

disposition of 114 

example of WTO 115 

identifier 115 

immediate action 115 

indicator in first character 114 

multiple-line (MLWTO) 114 

replying to 116 

routing 114 

sending to operator consoles 113 

single -line 114 
MLWTO (multiple-line messages), considerations for 

using 114 
module 

See also load module 

names 9 
multiple versions of load modules 30 
multiple-line (MLWTO) messages, considerations for 

using 114 
MVS router 

description 51 

parameter list 52 
MVS router interface 261 



N 



names 

duplicate 9 

of resources 43 
nonreenterable load modules 8 1 
nonreusable load module, passing control to 



37 



o 



obtaining a cell pool 145 

operator 

consoles, characters displayed 
messages, writing 113 

originating task 9 

overlay load module structure 18 

ownership of subpools 78 



113 







page 

faults, decreasing 107 

movement of 107 

releasing 107 

reusing 107 

size of 107 
page service list (PSL) 109 
page-ahead function 108 
paging I/O 107 

paging out virtual storage 108, 235, 242 
paging services 

input to 109 

list of 107 

PGLOAD macro instruction 232 

PGOUT macro instruction 235 

PGRLSE macro instruction 238 

PGSER macro instruction 242 
parallel execution, when to choose 9 
parameter addresses 

determining length of 120 

macros requiring 24-bit 120 
parameter area for recovery routines 59 
parameter list 

description of 20 

example of passing 21 

for macros, constructing 122 

indicating end of 22 

inline, use of 22 

location of 38, 122 

used in EVENTS processing 197 

variable length for macros 122 
parameter registers 3 
PARM field information 4 
partitioned data set directory entry 

See PDS directory entry 
passing control 

between control sections 20, 139 

between programs with different AMODEs 

between programs with the same AMODE 

in a dynamic structure 28-39 
with return 33 
without return 37 

in a simple structure 19-27 
with return 22 
without return 20 

preparing to 20, 22 

to another load module 222 

using a branch instruction 22, 37 

using CALL 23 

using LINK 33 

with a parameter list 21 

with control program assistance 33 

with return 22 

without control program assistance 19, 36 
passing parameters 

in lists 20, 79 



17,36 
17 
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in registers 79 

registers used 3 
passing return addresses 20 
PDS directory entry 

AMODE indicator 15, 222 

RMODE indicator 15,16 
percolation 59, 63, 65 
performing cell pool services 145 
PGLOAD macro instruction 

description 232 

example 233 

list form 234 

page-ahead function 108 

return codes 233 

standard form 232 

syntax 

of the list form 234 

of the standard form 232 

use of 107 
PGOUT macro instruction 

description 235 

example 236 

list form 237 

return codes 236 

standard form 235 

syntax 

of the list form 237 

of the standard form 235 

use of 107 
PGRLSE macro instruction 

description 238 

example 239 

execute form 241 

list form 240 

return codes 238 

standard form 238 

syntax 

of the execute form 241 

of the list form 240 

of the standard form 238 

use of 107, 108 
PGSER macro instruction 

addressing mode considerations 242 

description 242 

example 245 

input to 109 

page-ahead function 108 

return codes 244 

syntax 242 

use of 108 
PICA (program interruption control area) 

format 55 

pointer to 55 

purpose of 54 

restoring a previous 55 
PIE (program interruption element) 

format of 56 

purpose of 54 
planned overlay load module structure 18 



pointer-defined entry point address 17 

post bit 41 

POST macro instruction 

description 246 

example 247 

syntax 246 

use of 41 
PRB (program request block) 40 
preparing to pass control 

with return 22 

without return 20 
priority 

address space 10 

assigning 1 1 

changing 1 1 

control program's influence on 10 

dispatching 10 

higher, when to assign 1 1 

limit 10, 11 

subtask 1 1 

task 10 
private library 28 
processing a resource request 44 
program check, recovery 59 
program design 19 
program exceptions 

See program interruption 
program interruption 

causes 53 

control area, see PICA and fake PICA 

determining the cause of 56 

determining the type of 58 

element, see PIE and EPIE 

handling 53 
program management 15-40 
program mask 54 
program request block (PRB) 40 
program status word 

See PSW 
protecting resources 

via RACF 50 

via serialization 42 
providing a save area 6 
PSL (page service list) 109 
PSW (program status word) 

addressing mode bit 16, 17 

at time of error, field containing 65 

key assigned to the requestor 76 
purging the RB queue 67 
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qname of a resource 
purpose of 43, 173 
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RACF 

check authorization 248 
RACF (resource access control facility) 

function of 50 

macro instructions 
FRACHECK 201 
RACSTAT 267 

protection, determining status of 267 
RACHECK macro instruction 

chart of parameters by release 254 

description 248 

examples 256 

execute form 259 

list form 257 

return codes 255 

standard form 249 

syntax 249, 257, 259 

use of 50 
RACROUTE macro instruction 

description 261 

examples 264 

execute form 266 

list form 265 

return codes 263 

standard form 262 

syntax 262 

use of 52 
RACSTAT macro instruction 

chart of parameters by release 268 

description 267 

example 269 

execute form 271 

list form 270 

of the execute form 271 

reason codes 268 

return codes 268 

syntax 

of the execute form 271 

of the list form 270 

of the standard form 267 

use of 51 
RB (request block), purging queue of 67 
real storage management (RSM) 107-110 
real storage, loading into virtual storage 232 
reason code 

changing 60 

field containing 65 
receiving control, conventions for 8 
recovery routine 

altering register contents 58 

altering the old PSW 58 

avoiding recursion 59 

creating your own 63 

function performed by 58 

interfaces to ESTAEs 64 

parameter area for 59 
recovery termination manager (RTM), function of 59 



recovery/termination services 59 
recursion, avoiding in recovery routines 59 
reenterable 

load module 32, 36, 79 

macro instructions 79 

recovery routine 63 
refreshable module 81 
REGION system parameter 73 
register 

altering the contents of 58 

contents at time of error 65 

contents for a retry routine 68 

how the control program uses 3 

linkage 3 

saving 5 
register 1, passing parameters with 20 
register 13, use of 3 
register 14 

use of 3, 22 

when to restore 20 
register 15, use of 3, 20 
registers 2-12 22 
releasing 

a resource 46 

control of a load module 153 

serially reusable resources 155 

virtual storage 107 

virtual storage contents 238, 242 
replying to WTOR messages 116 
request block (RB), purging queue of 67 
requesting 

dumps 68 

serially reusable resources 173 
requests for resources 

limiting concurrent 44 
RESERVE macro instruction 43 
residency mode of programs 

See RMODE program attribute 
resource 

checking RACF authorization 201 

class, determining RACF protection of 267 

control 41-51 

global 43 

local 43 

making duplicate requests for 45 

name lists 43, 155, 173 

naming 43 

processing a request for 44 

protecting 

via RACF 50 

via serialization 42 

releasing 46 

requesting 

conditionally 46 
exclusive control of 44 
pairs of 50 
shared control of 44 
unconditionally 46 

serially reusable 

determining status of 173 
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releasing 155 
requesting 173 
use of 42 

types that can be shared 43 
resource access control facility 

See RACF 
responsibility count for a loaded module 33, 38, 82, 

227 
restoring 

a PICA 55 

I/O operations during retry processing 67 

registers upon return 25 
retry processing 59 
retry routines 

ESTAE/ESTAI 67 

interface to 67 

register contents 68 

requirements of 67 

restoring I/O operations 67 
return address 

location of 3 

passing 20 
return code area 

used in DEQ processing 157 

used in ENQ processing 177 
return codes 

analyzing 24 

establishing 26 

from ATTACH processing 134 

from CPUTIMER processing 152 

from DELETE processing 154 

from DEQ processing 158 

from DETACH processing 162 

from ENQ processing 177 

from ESPIE TEST processing 185 

from ESTAE processing 191 

from FRACHECK processing 204 

from FREEMAIN processing 210 

from GETMAIN processing 216 

from PGOUT processing 236 

from PGRLSE processing 238 

from PGSER processing 244 

register 4 

using 24 
RETURN macro instruction 

description 272 

example 273 

return codes 272 

syntax 272 

use of 25, 26 
returning 

a cell pool 145 

control 

in a dynamic structure 37 
in a simple structure 25 
reusability attributes of a load module 36 
reusable modules 32 
reusing a save area 22 
RMODE program attribute 

affect on load processing 227 



indicator in PDS entries 15 

purpose 15 

specifying 

in source code 15 

using linkage editor control cards 15 

use of 28 

values 16 
rname of a resource, purpose of 43, 173 
routing 

codes 114 

messages 114 
RSM (real storage management) 107-110 
RTM (recovery termination manager), function of 59 
RX-type address 124 



SAF (system authorization facility) 51 
save area 

address, register containing 3 
chaining 7 
creating 6 
format 5 

how to tell if used 26 
passing address of 20 
reusing 22 
SAVE macro instruction 
description 274 
example 275 
syntax 274 
use of 5, 40 
saving the calling program's registers 5 
scope of a resource 

changing 43, 155, 173 
STEP, when to use 43 
SYSTEM, when to use 43 
SYSTEMS, when to use 43 
use of 43, 173 
SDWA (system diagnostic work area) 64 
changing via SETRP 59 
key fields in 

SDWACCF bit 60, 65 

SDWACLUP bit 67 

SDWACMPC 60, 65 

SDWACOMU 65 

SDWACRC 60, 65 

SDWADAET 65 

SDWAEBC bit 65 

SDWAEC1 65 

SDWAEC2 65 

SDWAFAIN 65 

SDWAGRSV 65 

SDWAHEX bit 65 

SDWALNTH 65 

SDWAOCUR 65 

SDWAPARM 65 

SDWAREAF bit 60, 65 
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SDWASPID 65 
SDWASRSV 65 
SDWAURAL 65 
SDWAVRAL 65 

length, field containing 65 

mapping macro for 64 

obtaining storage for 64 
SDWA extensions 64 
SDWAVRA 64 
searching for a load module 29-32 

areas/libraries searched 30 

limiting 30 

order of 29, 30 
security 

data (see RACF) 1 
SEGLD macro instruction 

addressing mode considerations 120 

description 276 

example 276 

syntax 276 
SEGWT macro instruction 

addressing mode considerations 120 

description 277 

example 277 

syntax 277 
selecting the macro level 119-120, 129, 188, 194, 301, 

343 
serializing resources 

avoiding an interlock 49 

requesting exclusive control 44 

requesting shared control 44 
serially reusable 

modules 

obtaining a copy of 32 
passing control to 36 

resources 

releasing 155 
requesting 173 
serializing 173 
using 42-50 
services that the supervisor provides 1 
set a multiple timer 305 
SETRP macro instruction 

description 278 

example 280 

syntax 278 

use of 59, 66 

using 60 
shared resource control 44 
sharing subpools 77, 79 
signalling completion of an event 246 
simple load module structure 18, 19 
SNAP data control block 69 
SNAP dump 

index 70 

requesting 69 
SNAP macro instruction 

description 281 

example 286, 287 

execute form 290 

list form 288 



return codes 286 

standard form 282 

syntax 

of the execute form 290 

of the list form 288 

of the standard form 282 

use of 69 
specify program interruption exit 

See SPIE 
SPIE (specify program interruption exit) environment 

addressing mode of 54 

adjusting 55 

canceling 55 

definition 54 

reestablishing 55 
SPIE macro instruction 

addressing mode considerations 120 

addressing mode restrictions 54 

description 292 

example 294 

execute form 296 

list form 295 

standard form 293 

syntax 

of the execute form 296 

of the list form 295 

of the standard form 293 

use of 53, 54 
SPLEVEL macro instruction 

ATTACH macro's use of 129 

description 297 

ESTAE macro's use of 188 

EVENTS macro's use of 194 

example 298 

options 

SET 119,297 
TEST 297 

purpose of 119 

STIMER macro's use of 301 

syntax 297 

WTOR macro's use of 343 
SRM (system resource manager), function of 107 
STATUS macro instruction 

description 299 

example 300 

syntax 299 
step library 

reason for limiting size of 31 

use of 28 
STIMER macro instruction 

addressing mode considerations 301 

description 301 

example 304 

relationship to CPUTIMER macro 151 

SPLEVEL macro, use of 301 

syntax 301 
STIMERM CANCEL 

description 317 

examples 319, 320, 321 

execute form 321 
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list form 320 

return codes 318 

standard form 317 

syntax 317, 320, 321 
STIMERM macro instructions 

use of 111 
STIMERM SET 

description 305 

example 308,310,311 

execute form 311 

exit routine interface 307 

list form 310 

return codes 308 

standard form 305 

syntax 305,310,311 
STIMERM TEST 

description 312 

example 314, 315, 316 

execute form 316 

list form 315 

return codes 313 

standard form 312 

syntax 312, 315, 316 
storage 

See virtual storage 
storage request 

explicit 73 

implicit 73 
storage subpool, see subpool 76 
subpool 

creating 78 

handling 76 

IDoftheSDWA 65 

in task communication 79 

ownership of 78 

PSW key assignment 76 

sharing 77, 79 

transferring ownership 78 
subtask 

changing status of 299 

communications with tasks 1 1 

controlling 9 

creating 9 

detaching 161 

priority 1 1 

terminating 12, 41 
summary dumps 70 
supervisor services, introduction to 1 
SVC, recovery from invalid issuance 59 
switching addressing modes 

See addressing mode, changing 
symbol term in macro instruction description 123 
symptom dumps 69 
SYNCH macro instruction 

addressing mode considerations 322 

description 322 

example 

example of standard form 323 



of the execute form 325 
of the list form 324 
of the standard form 323 
execute form 325 
list form 324 
standard form 322 
syntax 

of the execute form 325 
of the list form 324 
of the standard form 322 
synchronizing tasks 41 
system authorization facility 51 
system conventions for parameter lists 20 
system diagnostic work area 

See SDWA 
SYSTEM inclusion resource name list 43, 155, 173 
system log, writing to 116 

system resource manager (SRM), function of 107 
SYSTEMS exclusion resource name list 155, 173 
SYSUDUMP PARMLIB member 69 







task 

advantage of creating additional 9 

communications with subtasks 1 1 

control block, see TCB 

creating 9, 129 

library, establishing 28 

priority, affect on processing 10 

synchronization 41 
TASKLIB parameter of ATTACH 28, 29 
tasks in a job step, illustration of 12 
TCB (task control block) 

address of 9 

removing 12 
test a time interval 312 
testing return codes 24 
time interval 

example of using 112 
TIME macro instruction 

description 326 

example 328 

syntax 326 

use of 111 
time of day and date, requesting 1 1 1 
time-of-day (TOD) clock 1 1 1 
timing services 111 
TOD (time-of-day) clock 1 1 1 
transferring control 

See passing control 
TTIMER macro instruction 

description 329 

example 330 

syntax 329 
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use count 34 
user exit routine 
See exit routine 
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V-type address constant, using to pass control 22 
V = R (virtual = real) storage, allocation of 107 
variable recording area 

See VRA 
virtual storage 

allocating 213 

bringing a load module into 227 

controlling 76 

explicit requests for 73 

freeing 82, 207 

implicit requests for 79 

loading 107, 108, 232, 242 

obtaining via CPOOL 75 

page-ahead function 108, 232 

paging out 108, 235, 242 

planning for future needs 232 

releasing 107, 108, 153 

releasing contents of 238, 242 

specifying the amount allocated to a task 73 

subpools 76 

using efficiently 73 
virtual storage management (VSM) 73-82 
virtual subarea list (VSL) 109 
virtual = real (V = R) storage, allocation of 107 
VRA (variable recording area) 

length of, field containing 65 

length used, field containing 65 
VSL (virtual subarea list) 109 
VSM (virtual storage management) 73-82 



to the system log 116 
WTL macro instruction 

description 334 

example 334 

execute form 336 

list form 335 

standard form 334 

syntax 

of the execute form 336 

of the list form 335 

of the standard form 334 

use of 116 
WTO macro instruction 

description 337 

descriptor code for 115 

example 115,340,342 

execute form 342 

list form 341 

multiple-line (MLWTO) form 

return codes 340 

single-line form 114 

standard form 337 

syntax 

of the execute form 342 

of the list form 341 

of the standard form 337 

use of 113 
WTOR macro instruction 

addressing mode considerations 

description 343 

example 116,344 

execute form 346 

ignored parameters 344 

list form 345 

SPLEVEL macro, use of 343 

standard form 343 

syntax 

of the execute form 346 

of the list form 345 

of the standard form 343 

use of 113 



114 



343 
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wait 

bit 41 

condition 41 

long 42 
WAIT macro instruction 

description 331 

example 332, 333 

syntax 331 

use of 41 
writing 

to the operator with reply 113 

to the operator without reply 1 1 5 

to the programmer 116 
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